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Licensing Requirements for Software Developers 

Apple has a low-cost licensing program, which permits developers of software 
for the Lisa to incorporate Apple-developed libraries and object code files 
into their products. Both in-house and external distribution require a license. 
Before distributing any products that incorporate Apple software, please 
contact Software Licensing at the address below for both licensing and 
technical information. 



©1983 by Apple Computer, Inc. 
20525 Mariani Avenue 
Cupertino, California 95014 

(408) 996-1010 



Apple, Lisa, and the Apple logo are trademarks of Apple Computer, Inc. 
Simultaneously published in the USA and Canada. 



Customer Satisfaction 

If you discover physical defects in the manuals distributed with a Lisa 
product or in the media on which a software product is distributed, Apple 
will replace the documentation or media at no charge to you during the 
90-day period after you purchased the product. 



Product Revisions 

Unless you have purchased the product update service available through 
your authorized Lisa dealer, Apple cannot guarantee that you will receive 
notice of a revision to the software described in this manual, even if you 
have returned a registration card received with the product. You should 
check periodically with your authorized Lisa dealer. 



Limitation on Warranties and Liability 

All implied warranties concerning this manual and media, including implied 
warranties of merchantability and fitness for a particular purpose, are 
limited in duration to ninety (90) days from the date of original retail 
purchase of this product. 

Even though Apple has tested the software described in this manual and 
reviewed its contents, neither Apple nor its software suppliers make any 
warranty or representation, either express or implied, with respect to this 
manual or to the software described in this manual, their quality, 
performance, merchantability, or fitness for any particular purpose. As a 
result, this software and manual are sold "as is," and you the purchaser are 
assuming the entire risk as to their quality and performance. 

In no event will Apple or its software suppliers be liable for direct, 
indirect, special, incidental, or consequential damages resulting from any 
defect in the software or manual, even if they have been advised of the 
possibility of such damages. In particular, they shall have no liability for 
any programs or data stored in or used with Apple products, including the 
costs of recovering or reproducing these programs or data 

The warranty and remedies set forth above are exclusive and in lieu of all 
others, oral or written, express or implied. No Apple dealer, agent or 
employee is authorized to make any modification, extension or addition to 
this warranty. 

Some states do not allow the exclusion or limitation of implied warranties 
or liability for incidental or consequential damages, so the above limitation 
or exclusion may not apply to you. This warranty gives you specific legal 
rights, and you may also have other rights that vary from state to state. 
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License and Copyright 

This manual and the software (computer programs) described in it are 
copyrighted by Apple or by Apple's software suppliers, with all rights 
reserved, and they are covered by the Lisa Software License Agreement 
signed by each Lisa owner. Under the copyright laws and the License 
Agreement this manual or the programs may not be copied, in whole or in 
part without the written consent of Apple, except in the normal use of 
the software or to make a backup copy. This exception does not allow 
copies to be made for others, whether or not sold, but all of the material 
purchased (with all backup copies) may be sold, given, or loaned to other 
persons if they agree to be bound by the provisions of the License 
Agreement. Copying includes translating into another language or format. 

You may use the software on any computer owned by you, but extra copies 
cannot be made for this purpose. For some products, a multiuse license 
may be purchased to allow the software to be used on more than one 
computer owned by the purchaser, including a shared-disk system. 
(Contact your authorized Lisa dealer for more information on multiuse 
licenses.) 



Product Revisions 

Unless you have purchased the product update service available through 
your authorized Lisa dealer, Apple cannot guarantee that you will receive 
notice of a revision to the software described in this manual, even if you 
have returned a registration card received with the product. You should 
check periodically with your authorized Lisa dealer. 
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Preface 



The Contents of This Manual 

This manual describes the Operating System service calls that are available to 
Pascal and assembler programs. It is written for experienced Pascal 
programmers and does not explain elementary terms and programming 
techniques. We assume that you have read the Lisa Owner's Guide and 
Workshop User's Guide for the Lisa and are familiar with your Lisa system. 

Chapter l is a general introduction to the operating system. 

Chapter 2 describes the File System and the available File System calls. This 
Includes a description of the interprocess communication facility, pipes, and 
the Operating System calls that allow processes to use pipes. 

Chapter 3 describes the calls available to control processes, and also describes 
the structure of processes. 

Chapter 4 describes how processes can control their use of available memory. 

Chapter 5 describes the use of events and exceptions that control process 
synchronization. It also describes the use of the system clock. 

Chapter 6 describes the calls you can use to find out about the configuration 
of the system. 

Appendix A contains the source text of Syscall, the unit that contains the 
type, procedure, and function definitions discussed in this manual. 

Appendix B contains a list of system-reserved exception names. 

Appendix c contains a list of system-reserved event names. 

Appendix D contains a list of error messages that can be produced by the 
calls documented in this manual. 

Appendix E contains a description of the information you can obtain from the 
Operating System about files and devices. 

Type and Syntax Conventions 

Bold-face type is used in this manual to distinguish programming keywords and 
constructs from English text. For example, FLUSH is the name of a system 
call. System call names are capitalized in this manual, although Pascal does 
not distinguish between lower and upper case characters, italics indicate a 
new term whose explanation follows. 
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Future Releases 

A few features of the Lisa Operating System will be changed in future 
releases: 

• Pipes will not be supported. 

• Timed events will not be supported 

• Configuration System Calls will be changed. 

If you want your software to be upward-compatible, please take these changes 
into consideration. More information is provided in the appropriate sections 
of the manual. 
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Introduction 



The Operating System (OS) provides an environment in which multiple processes 
can coexist, communicate, and share data. It provides a file system for I/O 
and information storage, handles exceptions (software interrupts), and performs 
memory management 

1.1 The Main Functions 

This chapter describes the four main functional areas of the OS: the File 
System, process management, memory management, and event and exception 
handling. 

The File System provides input and output. The File System accesses devices, 
volumes, and files. Each object, whether a printer, disk file, or any other type 
of object, is referenced by a pathname. Every I/O operation is performed as 
an uninterpreted byte stream. Using the File System, all I/O is device 
independent. The File System also provides device-specific control operations. 

A process consists of an executing program and its associated data Several 
processes can execute concurrently by multiplexing the processor between 
them. These processes can be broken into segments which are automatically 
swapped into memory as needed. 

Memory management routines handle data segments. A data segment is a file 
that can be placed in memory and accessed directly. 

Exceptions and events are process-communication constructs provided by the 
OS. An event is a message sent from one process to another, or from a 
process to itself, that is delivered to the receiving process only when the 
process asks for that event. An exception is a special type of event that 
forces itself on the receiving process. There is a set of system-defined 
exceptions (errors), and programs can define their own. System errors such as 
division ay zero are examples of system-defined exceptions. You can use the 
system calls provided to define any exceptions you want 

12 Using the OS Functions 

Both built-in language features and explicit OS system calls can access OS 
routines to perform desired functions. For example, the Pascal writeln 
procedure is a built-in feature of the language. The code to execute writeln 
is supplied in IOSPASLIB, the Pascal run-time support routines library. This 
code, which is added to the program when the program is linked, calls OS 
File System routines to perform the desired output. 

You can also call OS routines explicitly. This is usually done when the 
language does not provide the operation you want OS routines allow Pascal 
programs, for example, to create new processes, which could not otherwise be 
done, since Pascal does not have any built-in process-handling functions. 
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All calls to the OS are synchronous, which means they do not return until the 
operation is complete. Each call returns an error code to indicate if anything 
went wrong during the operatioa Any non-zero value indicates an error or 
warning. Negative error codes indicate warnings. For a list of error codes 
and their meaning, see Appendix D. 

13 The File System 

The File System performs all 1/0 as uninterpreted byte streams. These byte 
streams can go to files on disk or to other devices such as a printer or an 
alternative console. In all cases, the device or file has a File System name. 
Except for device-control functions, the File System treats devices and files 
in the same way. 

The File System allows sharing of all types of objects. 

The File system provides for naming objects (devices, files, etc.). A name in 
the File System is called a pathname A complete pathname consists of a 
directory name and a file name. The file name is meaningful only for storage 
devices (devices that store byte streams for later use, such as disks> 

Each process has a working directory associated with it. This allows you to 
reference objects with an incomplete pathname. To access an object in the 
working directory, you specify its file name. To access an object in a 
different directory, you specify its complete pathname. 

Before a device can be accessed, it must be mounted. Devices can be 
mounted using the Preferences tool or by using the MOUNT call. See Chapter 
2 for an explanation of this call and other File System calls. If the device is 
a storage device, the mount operation makes a volume name available. A 
volume name is a logical name for a disk, and is saved on the disk itself. The 
mount operation logically connects the volume to the system, so that the files 
on the volume may be accessed. The volume name can replace a device name 
in a pathname used to access an object on the disk. The volume name allows 
you to access a file with the same pathname no matter where the drive is 
actually connected. 

A device can be accessed if it is specified in the configuration list created by 
the Preferences tool, is physically connected to the Lisa, and is mounted. 
There are some operations that can be performed on unmounted devices. Two 
examples are DEYlCEjCONTROL calls and scavenging. Logically mounting a 
volume on a device makes file access to the volume possible. For storage 
devices, a volume is an actual magnetic medium that can contain recorded 
files. For non-storage devices, volumes and files are concepts used to 
maintain a uniform interface. Files on non-storage devices such as printers 
do not store data but act as ports for performing I/O to the devices. 
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The basic operations provided Dy the File System are as follows: 

mount and unmount - make a volume accessible/Inaccessible 
open and close - make an object accessible/Inaccessible 
read and write - transfer Information to and from an object 
device control functions - control device-specific functions 

Some operations apply only to storage devices: 

allocate and deallocate - specify size of an object 

manipulate catalog - control naming of objects and creation and 

destruction of objects 
manipulate attributes - look at or change the characteristics of 

the object 

In addition to the data in an object, the object itself has certain 
characteristics called attributes, such as the length and creation date of a 
file. Calls are available to access the attributes of any File System object. In 
addition to its system-defined attributes, an object on a storage device can 
have a labeL The label is available for programs to store information that 
they can Interpret 

Non-storage devices such as printers are accessed with a limited set of 
operations. They must be mounted and opened before they can be accessed. 
Sequential read and/or write operations are available as appropriate for the 
device. Device-control functions are available to perform any device- 
specific functions needed. The file-name portion of the complete pathname 
for a non-storage device is not used by the File System, although you do have 
to provide one when you open the device. 

For storage devices, the same sequential read and write operations are valid 
as for non-storage devices. Storage devices also must be mounted, and 
particular files opened, before the files can be used. They have appropriate 
device-control functions available. 

When writing to a disk file, space for the file is allocated as needed. Space 
for a file does not need to be contiguous, and in some cases this automatic 
allocation can result in a fragmented file, which may slow file access. To 
insure rapid access, you can pre-allocate space for the file. Pre-allocating 
the file also ensures that the process will not run out of space on the disk. 

Four types of objects can be stored on storage devices. These are files, pipes, 
data segments, and event channels. Files, already discussed, are simply arrays 
of stored data Pipes are objects that provide interprocess communicatloa 
Data segments are special cases of files that are loaded into memory along 
with program code. Event channels are pipes with a specialized structure 
imposed by the system. 

L4 Process Management 

A process is an executing program and the data associated with it Several 
processes can exist at one time, and they appear to run simultaneously 
because the CPU is multiplexed among them. The Scheduler decides what 
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process should use the CPU at any one time. It uses a generally non- 
preemptive scheduling algorithm. This means that a process will not lose the 
CPU unless it Blocks. The blocked state is explained later in this section. 

A process can lose the CPU when one of the following happens: 

• The process calls an operating system procedure or function. 

• The process references one of its code segments that is not currently in 
memory. 

If neither of these occur, the process will not lose the CPU. 

Every process is started by another process. The newly started process is 
called the son process The process that started it is called its father process 
The resulting structure is a tree of processes. See Figure 3-2 for an 
illustration of a process tree. 

When any process terminates, all its son processes and their descendants are 
also terminated. 

When the OS is booted, it starts a shell process The shell process starts any 
other processes desired by the user. 

Every newly created process has the same system-standard attributes and 
capabilities. These can be changed by using system calls. 

Any processes can suspend, activate, or kill any other process for which the 
global ID is known, as long as the other process does not protect itself. 

The memory accesses of an executing process are restricted to its own 
memory address space. Processes can communicate with other processes by 
using shared files, pipes, event channels, or shared data segments. 

A processcan be in one of three states: ready, running, or blocked. A ready 
process \% waiting for the Scheduler to select it to run. A running process Is 
currently using the CPU to execute its code. A blocked process Is waiting for 
some event, such as the completion of an I/O operation. It will not be 
scheduled until the event occurs, at which point it becomes ready. A 
terminated process tos finished executing. 

Each process has a priority from l to 255. The higher the number, the higher 
the priority of the process. Priorities 226 to 255 are reserved for system 
processes. The Scheduler always runs the ready process with the highest 
priority. A process can change its own priority, or the priority of any other 
process, while it is executing. 

15 Memory Management 

Memory managment is concerned with what is in physical memory at any one 
time. Each process can use up to 128 memory segments. Each segment can 
contain up to 128 Kbytes. Memory segments are of two types: code segments 
and data segments. The total amount of memory used by any one process can 
exceed the available RAM of the Lisa The Operating System will swap code 
segments in and out of memory as they are needed. To aid the Operating 
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System In swapping data segments, calls are provided to give programs the 
ability to define which data segments must be in memory while a particular 
part of the program is executing. 

You have control of how your program is divided up. For executable code 
segments, you use the segmentation commands of the Pascal compiler to break 
the program in pieces. 

In addition to residing in memory, data segments can be stored permanently 
on disk. They can be accessed with calls similar to File System calls. This 
allows you to use a data segment as a direct-access file—a file that is 
accessed as part of your memory space. 

Calls are provided for making, killing, opening, and closing data segments. 
You can also change the size of a data segment and set its access mode to 
read-only or read-write. In addition, you can make a permanent disk copy of 
the contents of a data segment at any time. Other calls give you ability to 
force the contents of the data segment to be swapped into main memory so 
they can be accessed by your process. 

1.6 Exceptions and Events 

An exception is an unexpected condition in the execution of a process (an 
interrupt). An event is a message from another process. 

An exception can be generated either by the system or by an executing 
program. System exceptions are generated by various sorts of errors such as 
divide by zero. Illegal instruction, and illegal address, system exception 
handlers are supplied that terminate the process. You can write your own 
exception handlers for any of these exceptions if you want to try to recover 
from the error. 

user exceptions can be declared and exception handlers can be written to 
process them. Your program can then signal this new exception. 

Events are messages sent from one process to another. They are sent through 
event channels. 

A process that expects a message from an event channel executes a call to 
wait for an event on that channel. This will give it the next message, if one 
exists, or block the process until a message arrives. 

If a process wants to know when an event arrives, but does not want to wait 
for it, it can use an event-call channel. This is set up by associating a user 
exception with the event channel when it is opened. The Operating System 
will then invoke the corresponding user exception handler whenever a message 
arrives in the event channel. 

L7 interprocess Communication 

There are four methods for interprocess communication: shared files, pipes, 
event channels, and shared data segments. 
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Shared files are used for high volume transfers of Information. It Is necessary 
to coordinate the processes somehow to prevent them from overwriting each 
other's Information. 

Pipes are used for communication between processes with an uninterpreted 
byte stream. (Note that pipes will not be supported in future releases of the 
Operating System.) The pipe mechanism provides for the needed 
synchronization; a process will block if it is trying to read from an empty 
pipe or write to a full one. A read from a pipe consumes the information, so 
it is no longer available. Only one process can read from a given pipe. 

Event channels are similar to pipes, except that event channels transmit short, 
structured messages instead of uninterpreted bytes. 

A shared data segment can be used to transmit a large amount of data 
rapidly. Having a shared data segment means that this data segment is in the 
memory address space of all the processes that want to use it All the 
processes can then directly read and write information in the data segment. 
It is necessary to provide some sort of synchronization to keep one process 
from overwriting another's information. 

1.8 Using the OS Interface 

The Interface to all the system calls is provided in the syscail unit, found in 
Appendix A This unit can be used to provide access to the calls. See the 
Workshop users Guide for the Lisa for more information on using Syscail. 

1.9 Running Programs Under the OS 

Programs can be written and run by using the Workshop, which provides 
program development tools such as editing and debugging facilities. 

1.10 writing Programs That Use the OS 

You can write a program that calls OS routines to perform needed functions. 
This program uses the Syscail unit and then calls the routines needed. 
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The File System 



The File System provides device-independent I/O, storage with access 
protection, and uniform file-naming conventions. 

Device independence means that all I/O is performed in the same way, 
whether the ultimate destination or source is disk storage, another program, a 
printer, or anything else. In all cases, I/O is performed to or from files, 
although those files can also be devices, data segments, or programs. 

Every file is an uninterpreted stream of eight-bit bytes. 

A file that is stored on a block-structured device, such as a disk, is listed in 
a catalog (also called a director^ and has a name. For each such file the 
catalog contains an entry describing the file's attributes, including the length 
of the file, its position on the disk, and the last backup copy date. Arbitrary 
application-defined information can be stored in an area called the file label 
Each file has two associated measures of length, the Logical End of File 
(LEOF) and the Physical End of File (PEOF) The LEOF is a pointer to the last 
byte that has meaningful data. The PEOF is a count of the number of blocks 
allocated to the file. The pointer to the next byte to be read or written is 
called the file marker. 

Since I/O is device independent, application programs do not have to take 
account of the physical characteristics of a device. However, on block- 
structured devices, programs can make I/O requests in whole-block increments 
in order to improve program performance. 

All input and output is synchronous in that the I/O requested is performed 
before the call returns. The actual I/O, however, is asynchronous, in that 
processes may block when performing I/a See Section 35, Process Scheduling, 
for more information on blocking. 

To reduce the impact of an error, the File System maintains distributed, 
redundant information about the files on storage devices. Duplicate copies of 
critical information are stored in different forms and in different places on 
the media. All the files are able to identify and describe themselves, and 
there are usually several ways to recover lost information. The Scavenger 
utility is able to reconstruct damaged catalogs from the information stored 
with each file. 

2.1 File Names 

All the files known to the Operating System at a particular time are organized 
into catalogs. Each disk volume has a catalog that lists all the files on the 
disk. 

Any object catalogued in the File System can be named Dy specifying the 
volume on which the file resides and the file name. The names are separated 
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by the character "-". Because the top catalog In the system has no name, all 
complete pathnames begin with "-". 

For example, 

-LISA-FORMAT. TEXT 

refers to a file named format. TEXT on a volume named LISA. The file 
name can contain up to 32 characters. If a longer name is specified, the 
name is truncated to 32 characters. Accesses to sequential devices use an 
arbitrary dummy filename that is ignored but must be present in the 
pathname. For example, the serial port pathname 

-RS232B 

is insufficient, but 

-RS232B-XYZ 

is accepted, even though the -XYZ portion is ignored Certain device names 
are predefined: 

RS232A serial Port A 

RS232B Serial Port B 

PARAPORT Parallel Port 

SLOTxCHANy serial ports: x is 1, 2, or 3 and y is l or 2 

mainconsole wrlteln and readln device 

ALTCONSOLE wrlteln and readln device 

UPPER upper Diskette drive (Drive l) 

LOWER Lower Diskette drive (Drive 2) 

BITBKT Bit bucket: data Is thrown away when directed here 

See Chapter 6 for more information on device names. 

upper and lower case are not significant in pathnames: , TESTV0L' is the same 
object as 'TestVol*. Any ASCII character is legal in a pathname, including 
non-printing characters and blank spaces. However, use of ASCII 13, 
RETURN, In a pathname Is strongly discouraged. 

22 The working Directory 

It is sometimes inconvenient to specify a complete pathname, especially when 
working with a group of files in the same volume. To alleviate this problem, 
the Operating System maintains the name of a working directory for each 
process. When a pathname is specified without a leading "-", the name refers 
to an object in the working directory. For example, if the working directory 
is -LISA the name FORMAT.TEXT refers to the same file as 
-LISA-FORMAT.TEXT. The default working directory name is the name of the 
boot volume directory. 

You can find out what the working directory is with GET_WORKINGJDIR. 
You can change to a new working directory with SET_W0RKING_DIR. 
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23 Devices 

Device names follow the same conventions as file names. Attributes like baud 
rate are controlled by using the DEVICE_C0NTR0L call with the appropriate 
pathname. 

Each device has a permanently assigned priority. From highest to lowest, the 
priorities are: 

Power on/off button 

Serial port A (RS232A) 

Serial port B (RS232B, the leftmost port) 

I/O slot 1 

I/O slot 2 

I/O slot 3 

Keyboard, mouse, battery-powered clock 

10 ms system timer 

CRT vertical retrace interrupt 

Parallel port 

Diskette 1 (UPPER) 

Diskette 2 (LOWER) 

Video screen 

The device driver associated with a device contains information about the 
device's physical characteristics such as sector size and interleave factors for 
disks. 

2.4 Storage Devices 

On storage devices such as disk drives, the File System reads or writes file 
data in terms of pages. A /as^eis the same size as a block. Any access to 
data in a file ultimately translates into one or more page accesses. When a 
program requests an amount of data that does not fit evenly into some 
number of pages, the File system reads the next highest number of whole 
pages. Similarly, data is actually written to a file only in whole page 
increments. 

A file does not need to occupy contiguous pages. The File System keeps 
track of the locations of all the pages that make up a file. 

Each page on a storage device is self-identifying; the page descriptors stored 
with the page contents to reduce the destructive impact of an I/O error. 

The eight components of the page descriptor are: 

Version number 

volume identifier 

File identifier 

Amount of data on the page 

Page name 

Page position in the file 

Forward link 

Backward link 
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Each volume has a Medium Descriptor Data File (MDDF)*M&\ describes the 
various attributes of the medium such as its size, page length, block layout, 
and the size of the boot area. The MDDF is created when the volume is 
initialized. 

The File System also maintains a record of which pages on the medium are 
currently allocated, and a catalog of all the files on the volume. Each file 
contains a set of file hints, which describe and point to the actual file data. 

2.5 The Volume Catalog 

On a storage device, the volume catalog provides access to the files. The 
catalog is itself a file that maps user names into the internal file identifiers 
used by the Operating System. Each catalog entry contains a variety of 
Information about each file including: 

Name 

Type 

Internal file number and address 

Size 

Date and time created, last modified, and last accessed 

File identifier 

Safety switch 

The safety switch is used to avoid accidental deletions. While the safety 
switch is on, the file cannot be deleted. The other fields are described under 
the LOOKUP File System call. 

The catalog can be located anywhere on the medium. 

2.6 Labels 

An application can store its own information about a file in an area called 
the file label The label allows an application to keep the file data separate 
from information maintained about the file. Labels can be used for any 
object in the File System. The maximum label size is 128 bytes. I/O to labels 
is handled separately from file data I/a 

2.7 Logical and Physical End of File 

A file contains some number of bytes of data recorded in some number of 
physical pages. Additional pages which do not contain any file data can be 
allocated to the file. There are, therefore, two measures of the end of the 
file. The Logical End of File (LEOF) is a pointer to the last stored byte that 
has meaning to the application. The Physical End of File (PEOF) is a count of 
the number of pages allocated to the file. 

In addition, each open file has a pointer called the file /raswterwhlch points 
to the next byte in the file to be read or written. When the file is opened, 
the file marker points to the first byte (byte number 0). The file marker can 
be positioned automatically or explicitly using the read and write calls. For 
example, when a program writes to a file opened with Append access, the file 
marker is automatically positioned to the end of the file before new data are 
written. The file marker cannot be positioned past LEOF except by a write 



2-4 



Operating System Reference Manual Tne File System 

operation that appends data to a file; in this case tne file marker is 
positioned one byte past LEOF. 

When a file is created, an entry for it is made in the catalog specified in its 
pathname, but no space is allocated for the file itself. When the file is 
opened by a process, space can be allocated explicitly by the process, or 
automatically by the Operating System. If a write operation causes the file 
marker to be positioned past the LEOF marker, LEOF (and PEOF if necessary) 
are automatically extended. The new space is contiguous if possibla 

2.8 File Access 

The File System provides a device-Independent bytestream Interface. As far 
as an application program is concerned, a specified number of bytes is 
transferred either relative to the file marker or at a specified byte location 
in the file. The physical attributes of the device or file are not important to 
the application, except that devices that do not support positioning can 
perform only sequential operations. Programs can sometimes Improve 
performance, however, by taking advantage of a device's physical 
characteristics. 

Programs can request any amount of data from a file. The actual I/O, 
however, is performed in whole-page increments when devices are block 
structured. Therefore, programs can optimize I/O to such devices by setting 
the file marker on a page boundary and making I/O requests in whole-page 
increments. 

A file can be open for access by more than one process concurrently. All 
requests to write to the file are completed before any other access to the file 
Is permitted. When one process writes to a file, the effect of the write 
operation is immediately available to all other processes reading the file. The 
other processes may, however, have accessed the file in an earlier state. 
Data already obtained by a program are not changed. The programmer must 
ensure that processes maintain a consistent view of a shared file. 

When you open a file, you specify the kind of access allowed on the file. 
When the file is opened, the Operating System allocates a file marker for the 
calling process and a run- time identification number called the refnum The 
process must use the refnum in subsequent calls to refer to the file. Each 
operation using the refnum affects only the file marker associated with that 
refnum. 

Processes can share the same file marker. In glooal access mode, each 
process uses the same refnum for the file. When a process opens a file in 
global access mode, the refnum it gets back can be passed to any other 
process, and used by any process. Note that any number of processes can 
open a file with Global_Refnura but each time the GPEN call is used a 
different refnum is produced. Each of those refnums can be passed to other 
processes, and each process using a particular refum shares the same file 
marker with other processes with the same refum. Processes using different 
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refnums, however, always have different file markers, whether or not those 
refnums were obtained with Global Jtefnum. 

A file can also be opened in private mode, which specifies that no other OPEN 
calls are to be allowed for that file. A file can be opened with 
Global_Refrium and private, which opens the file for global access, but allows 
no other process to open that file. By using this call, processes can control 
which other processes have access to a file. The opening process passes the 
global refnum to any other process that is to have access, and the system 
prevents other processes from opening the file. 

Processes using global access may not be able to make any assumptions about 
the location of the file marker from one access to the next 

2.9 Pipes 

Because the operating System supports multiple processes, a mechanism is 
provided for interprocess communication. This mechanism is called a pipe 
Pipes are similar to the other objects in the File System ~ they are named 
according to the same rules, and they can have labels. 

NOTE 

Pipes will not be supported in future releases of the operating System. 
Do not use the pipe mechanism if you want your software to be 
upward-compatible. 

As with a file, a pipe is a byte stream. With a pipe, however, information is 
queued In a flrst-ln-flrst-out manner. Also, a pipe can have only one reader 
at a time, and once data is read from a pipe it is removed from the pipe. 

A pipe can be accessed only in sequential mode. Although only one process 
can read data from a pipe, any number of processes can write data into it. 
Because the data read from the pipe is consumed, the file marker is always at 
zero. If the pipe is empty and no processes have it open for writing, EOF (End 
Of File) is returned to the reading process. If any process has the pipe open 
for writing, the reading process is suspended until enough data to satisfy the 
call arrives in the pipe, or until all writers close the pipe. 

When a pipe is created, its size is bytes. Unlike with ordinary files, the 
initializing program must allocate space to the pipe before trying to write 
data into It To avoid deadlocks between the reading process and the writers, 
the Operating System does not allow a process to read or write an amount of 
data greater than half the physical size of the pipe. For this reason, you 
should allocate to the pipe twice as much space as the largest amount of data 
in any planned read or write operatioa 

A pipe is actually a circular buffer with a read pointer and a write pointer. 
All writers access the pipe through the same write pointer. Whenever either 
pointer reaches the end of the pipe, it wraps back around to the first byte. If 
the read pointer catches up with the write pointer, the reading process blocks 



2-6 



Operating System Reference Manual The File System 

until data are written or until all the writers close the pipe. Similarly, if the 
write pointer catches up with the read pointer, a writing process blocks until 
the pipe reader frees up some space or until the reader closes the pipe. 
Because pipes have this structure, there are restrictions on some operations. 
These restrictions are discussed with the relevant File System calls. 

Processes can never make read or write requests bigger than half the size of 
the pipe because the Operating System always fully satisfies each read or 
write request before returning to the program. In other words, if a process 
asks for 100 bytes of data from a pipe, the Operating System waits until there 
are 100 bytes of data in the pipe and then completes the call. Similarly, if a 
process tries to write 100 bytes of data into a pipe, the Operating System 
waits until there is room for the full 100 bytes before writing anything into 
the pipe. If processes were allowed to make write or read requests for 
greater than half of a particular pipe, it would be possible for a reader and a 
writer to deadlock, with neither having room in the pipe to satisfy its 
requests. 

2.10 File System Calls 

This section describes all the operating System calls that pertain to the File 
System. A summary of all the Operating System calls can be found in 
Appendix A The following special types are used in the File System calls: 

Pathname = STRING[Kax_Pathname]; (* Max_Pathnaine = 255 *) 
E_Name = STraNG[ttax_Enane]; (* Max_EName = 32 ») 

Accesses = (Dread, Dwrite, Append, Private, Global_Refnum); 
MSet = SET OF Accesses; 
Iottode = (Absolute, Relative, Sequential); 

The Fsjnfo record and its associated types are described under the LOOKUP 
call. The Dctype record is described under the DEVICE_C0MTR0L call. 
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ziai make_file and make_pipe File system calls 

riAKE_FlLE (Var Ecode: integer; 
Var Path: Pathname; 
l_abel_Size : Integer ) 

MAKE_PIPE (Var Ecode: Integer; 
Var Path: Pathname; 
Label_Size: Integer ) 

Ecode: Error indication 

Path: Name of new object 

Ladel_Size: Number of bytes for the object's label 

MAKE_FILE and MAKE_PIPE create the specified type of object with the 
given name. If the pathname does not specify a directory name (more 
specifically, if the pathname does not begin with a dash), the working 
directory is used. Label_Size specifies the initial size in bytes of the label. 
It must be less than or equal to 128 bytes. The label can grow to contain up 
to 128 bytes no matter what its initial size. Any error indication is returned 
in Ecode. 

NOTE 

Pipes will not be supported in future releases of the Operating System. 
Do not use the pipe mechanism if you want your software to be 
upward-compatible. 



The MAKE_FILE example on the next page checks to see whether the 
specified file exists before opening it 
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(* get a file name *) 



CONST FileExlStS = 890; 
VAR FileRefNuH\,ErrorCode:INTEGER; 
FileName:PathName; 
Happy : BOOLEAN; 
Response:CHAR; 
BEGIN 

Happy :=FALSE; 
WHILE NOT Happy DO 
BEGIN 
REPEAT 

•RITECFIle name: '); 
READLN(FileNaWB); 
UNTIL LENGTH(FileName)>0; 

hAKE_FILE(ErrorCode^FileNanie,0); (*no label for this file*) 
IF (ErrorCodeoO) THEN (* does file already exist? *) 
IF (ErrorCode=FileExists) THEN (* yes *) 

BEGIN 

•RITE(FileName, ' already exists. Overwrite? '); 
READLN(Response); 

Happy := (Response IN [•yW]); (*go ahead and overwrite*) 
END 

ELSE •RITELNCError '.ErrorCode, ' while creating file.') 
ELSE Happy ^TRUE.- 
END; 

OPEN(ErrorOode.FileNaRB.FileRefNUBi [Dwrite]); 

END; 
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2.102 KILLJBJECT File System Call 

KILLJBJECT (Var Ecode: Integer; 
Var Path: Pathname) 

Ecode: Error indicator 

Path: Name of object to be deleted 

KILLJBJECT deletes the object given in Path from the File System. Objects 
with the safety switch on cannot be deleted. If a file or pipe is open at the 
time of the KILL_0BJECT call, its actual deletion is postponed until it has 
\yem closed by all processes that have it opea During this period no new 
processes are allowed to open it. The object to be deleted need not be open 
at the time of the KILLJBJECT call. A KILLJBJECT call can be reversed 
by UNKILL_FILE, as long as the object is a file and is still open. 

The following program fragment deletes files until return is pressed: 

CONST FileN0tF0Und=89A; 
VAR Filename :PathNanie; 
ErrorCode : INTEGERS- 
BEGIN 
REPEAT 

•RITECFile to delete: '); 
READLN(FileName); 
IF (FileNaweo") THEN 
BEGIN 

KILLJBJECT(EiTorCode, Filename); 
IF (ErrorCodeoO) THEN 
IF (ErrorCode=FileNotFound) THEN 
•RITELNCFileName, * not found.') 

ELSE WtlTELNC Error , ,ErrorCode, ' ihile deleting file.') 
asE «RITELN(FiieName, ' deleted. * ); 
END 
UNTIL (FileName^*); 
END; 
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2.10.3 UNKILL_FILE File System call 

UNKILL_FILE (Var Ecode : Integer; 
RefNum: Integer; 
Var Newname :e_name) 

Ecode: Error indicator 

RefNum: Refnum of the killed and open file 

Newname: New name for the file being restored 

unkill_file reverses the effect of KILLJBJECT as long as the killed 
object Is a file that is still open. A new catalog entry is created for the file 
with the name given in Newname. Newname is not a full pathname: the 
resurrected file remains in the same directory. 
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2.10.4 rename_entry File system call 

RENAMEJENTRY (Var Ecode: Integer; 
Var Path: Pathname; 
Var Newname:E_Name) 

Ecode: Error indicator 
Path: Object's old name 
Newname: Object's new name 

RENAMEJENTRY changes the name of an object in the File System. 
Newnarne cannot be a full pathname. The name of the object Is changed, but 
the object remains In the same directory. The following program fragment 
changes the file name of FORMATTER.LIST to NEWFORMAT.TEXT. 

VAR oldNawerPathNane; 

NewName:E_Name; 

ErrorCode: INTEGER 
BEGIN 

OldName^' -LISA-FORMATTER.LIST*; 

NeKName : = ' NEHF ORMAT . TEXT * ; 

RENAME_ENTRY(ErrorCode, OldName, NenName); 

END; 

The file's full pathname after renaming is 

-LISA-NEWFORMAT.TEXT 

Volume names can be renamed by specifying only the volume name in Path. 
Here is a sample program fragment which changes a volume name. Note that 
the leading dash (-), given in QldName, is not given in NewName. 

VAR 01dName:PathName; 

NetfName:E_Name; 

ErrorCode: INTEGER 
BEGIN 

OldName : = * -thomas * ; 

NewName :=' steams'; 

RENAME_ENTRY(Errorcode, OldName, NewName); 
END; 
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2.10.5 LOCKUP File System Call 

LOOKUP (Var Ecode:Integer; 
Var Path: Pathname; 
Var Attributes :Fs_Info) 

Ecode: Error indicator 

Path: Object to lookup 

Attributes: Information returned about path 

LOOKUP returns information about an object in the file system. For devices 
and mounted volumes, call LOOKUP with a pathname that names the device or 
volume without a file name component: 

DevName:=' -UPPER*; (• Diskette drive 1 *) 

L00KUP(ErrorCode, DevName, Inf oRec); 

If the device is currently mounted and is block structured, all of the record 
fields of Attributes contain meaningful values; otherwise, some values are 
undefined. 

The Fsjnfo record is defined as follows. The meanings of the information 
fields are given in Appendix E. 

FS_Inf O = RECORD 

name: ejrane; 
devnum: INTEGERS- 
CASE OType:info_type OF 

device_t, volume_t: 

(iochamel: INTEGER 

devt: devtype; 

Slot_no: INTEGER; 

fs_size: LONGINT; 

VOl_Size: LONGINT; 

blockstmctured, 

mounted: BOOLEAN; 

opencount: LONGINT; 

prlvatedev, 

remote, 

lockeddev: BOOLEAN; 

mount_pending, 

unmount jpending: BOOLEAN; 

volnane, 

password: e_name; 

fsversica 

volid, 

volnum: INTEGER; 
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END; 



blocksize, 

datasize, 

clustersize, 

filecount: INTEGER; (*Number of files on vol*) 

freecount: LWJGINT; ("Number of free blocks *) 

DTVC, (* Date Volume Created •) 

DTVB, (* Date Volume last Backed up *) 

DTVS:LONGINT;(* Date Volume last scavenged «) 

Machine_id, 

overmount_stamp, 

master_copy_id: LONGINT; 

privileged, 

•rIte_protected: BOOLEAN; 

master, 

copy, 

scavenge_flag: BOOLEAN); 
0DJect_t: ( 

size: LONGINT; (~actual no of bytes written *) 

psize: LONGINT; ("physical size in bytes *) 

lpsize: INTEGER; ("Logical page size in bytes *) 

ftype: filetype; 

etype: entrytype; 

DTC, (< 

DTA, (< 

DTtt (« 

DTB: LONGINT; (< 

refnum: 

fmark: LONGINT; (* file marker •) 

acmode: inset; (* access mode *) 

nreaders, (* Number of readers •) 
(* Number of writers *) 
INTEGER; (* Number of users *) 
uid; (« unique identifier *) 
(* EOF encountered? •) 
(* safety switch setting 
(* has file been killed? 

private, (* File opened for private access? 

locked, (• Is file locked? *) 

protected : BOOLEAN); (* File copy protected? 



LONGINT; 
INTEGER; 
LONGINT; 

inset; 

nwriters, 

nusers: 

fuid: 

eof, 

safetyjon, 

kSUitCh: BOOLEAN; 



Date Created 
Date last Accessed 
Date last Modified 
Date last Backed up 
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Old = INTEGER; 

Info_Type = (devlce_t, volume_t, obJect_t); 

Devtype = (dlskdev, pascalbd, seqdev, bltbkt, non_lo); 

Filetype = (undefined, MDOFFile, rootcat, freellst, 

badblocks, sysdata, spool, exec, usercat, pipe, 

bootf lie, svapdata, svapcode, ramap, userflle, 

kllledobject); 
Entrytype ■ (emptyentry, catentry, linkentry, fileentry, 

plpeentry, ecentry, kllledentry); 

The eof field of the Fsjnfo record Is set after an attempt to read more 
bytes than are available from the file marker to the logical end of the file, or 
after an attempt to write when no disk space is available. If the file marker 
is at the twentieth byte of a twenty-five byte file, for example, you can 
read up to 5 bytes without setting eof, but if you try to read 6 bytes, the 
File System gives you only 5 bytes of data and eof is set 

The following program reports how many bytes of data a given file has: 

VAR InfoRec.-Fs Inf o; ("Information returned by LOOKUP and INFO*) 
FileNamezPathName; 
Er rorCode : INTEGER; 
BEGIN 
•RITECFlle: '); 
READLN(FlleName); 

LOOKUP(ErrorCode, FlleName, inf oRee); 
IF (Errorcode<>o) THEN 
VRITELN( 'Cannot lookup ', FlleName) 

ELSE 

«RlTELN(FlieName, ' has MnfoRec.slze, * bytes of data.*); 

END; 
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2.10.6 INFO File System Call 

INFO (Var Ecode : Integer; 
RefNiiB: Integer; 
Var Reflnfo:Fs_lnfo) 

Ecode: Error indicator 

RefNum: Reference number of object in File System 

Refinfo: Information returned about RefNum* s object 

INFO serves a function similar to that of LOOKUP but is applicable only to 
objects in the File System that are open. The definition of the Fsjnfo 
record is given under LOOKUP and in Appendix A. 
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2.10.7 SETFILEJNFO File System Call 

SET_FILE_INFO ( Var Ecode : Integer; 
RefNum:Integer; 
Fsi:Fs_Info) 

Ecode: Error indicator 

RefNum: Reference number of object in File System 

Fsi: New information about tne object 

SET_FILE_INFO cbanges tne status information associated witn a given object, 
mis call works in exactly tne opposite way tnat LOOKUP and INFO work, in 
tbat tne status information is given by your program to SET_FILE_INFO. Tne 
Fsl argument is tne same type of information record as tnat returned by 
LOOKUP and INFO. Tne object must be open at tne time this call is made. 

Tne following fields of tne information report may be cnanged: 

file_scavenged 
file_closed by_ps 
file_left_open 
user_type 
usersubtype 
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2.1CL8 OPEN File System Call 

OPEN (var Ecode:Integer; 
Var Path:Pathname; 
var RefNun: integer; 

Manlp.-MSet) 

Ecode: Error Indicator 

Path: Name of object to be opened 

RefNum: Reference number for object 

Manip: Set of access types 

The OPEN call opens an object so that it can be read or written to. When 
you call OPEN, you specify the set of accesses that will be allowed on that 
file or sequential device. The available access types are: 

• Dread — Allows you to read the file 

• Dwrite — Allows you to write in the file (to replace existing 
data) 

• Append ~ Allows you to add on to the end of the file 

• Private — Prevents other processes from opening the file 

• GlobalRefnum ~ Creates a refnum that can be passed to other 
processes 

Note that you can give any number of these modes simultaneously. If you 
specify Dwrite and Append in the same OPEN call, Dwrite access will be used. 
See Section 2.8 for more information on Global Refmm and Private access 
modes. 

If the object opened already exists and the process calls WRITE_DATA 
without having specified Append access, the object can be overwritten. The 
Operating System does not create a temporary file and wait for the 
CLOSEJBJECT call before deciding what to do with the old file. 

An object can be opened by two separate processes (or more than once by a 
single process) simultaneously. If the processes write to the file without using 
a global refnum, they must coordinate their file accesses so as to avoid 
overwriting each other's data 

Pipes cannot be opened for Dwrite access. You must use Append if you want 
to write into the pipe. To set up a private pipe, the reader process opens the 
pipe first, specifying Dread mode; the writer process then opens the pipe with 
Append Private access mode. 
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2.10.9 closejbject File System call 

CLOSEJBJECT (Var Ecode: Integer; 
RefNumanteger) 

Ecode: Error indicator 

RefNum: Reference number of object to be closed 

If RefNum is not global, CLOSEjDBJECT terminates any use of RefNum for I/O 
operations. A FLUSH operation is performed automatically and the file is 
saved in its current state. If RefNum is a global refnum and other processes 
have the file open, RefNum remains valid for these processes and other 
processes can still access the file using RefNum 

The following program fragment opens a file, reads 512 bytes from it, and 
then closes the file. 

TYPE Byte=-128.. 127; 
VAR Filename -.PathName; 

ErrorCode, FileRefNumrlnteger; 
ActualBytesrLonglnt; 
Buffer:ARRAY[0. .511] OF Byte; 
BEGIN 
OPEN(EirortX)cte,FlleNaflB.FlleRefNuni, [DRead]); 
IF (ErrorOode>0) THEN 

•RITELNC Cannot open '.FileName) 
aSE 
BEGIN 
READ_DATA(ErrorCode, 
FileRefNum, 
0RO4(aBuffer), 
512, 

ActualBytes, 
Sequential, 
0); 
IF (ActualBytes<512) THEN 

*RITE(*0nly read *, ActualBytes, ' bytes from , ,FileNaroe); 
CLrjSEJ)BJECT(EiTorCode,FileRefNuin); 
END; 
END; 
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2.10.10 READJDATA and write_data File system calls 

READJDATA (var Ecode: integer; 
RefNum: Integer; 
Data_Addr :LongInt; 
Count :LongInt; 
Var Actual :LongInt; 
Mode:Ionode; 
Offset :LongInt); 

*RITE_DATA (Var Ecode : Integer; 
RefNum: Integer; 
Data_Addr :Longint; 
Count :LongInt; 
Var Actual :Longlnt; 
ttode:Iottode; 
OffsetrLonglnt); 

Ecode: Error indicator 

RefNum: Reference number of object for I/O 

Data_Addr: Address of data (source or destination) 

Count: Number of bytes of data to be transferred 

Actual: Actual number of bytes transferred 

Mode: I/O mode 

Offset: Offset (absolute or relative modes) 

READ_DATA reads Information from the device, pipe, or file specified by 
RefNum, and WRITE_DATA writes information to it. Data_Addr is tne 
address for tne destination or source of Count bytes of data. Tne actual 
number of bytes transferred is returned in Actual. 

Mode can be absolute, relative, or sequential, in absolute mode. Offset 
specifies an absolute byte of tne file. In relative mode, Offset specifies a 
byte relative to tne file marker, in sequential mode. Offset is ignored 
(assumed to be zero); transfers occur relative to the file marker. Sequential 
mode (which is a special case of relative mode) is the only access mode 
allowed for reading or writing data in pipes or sequential (non-disk) devices. 
Non-sequential modes are valid only on devices that support positioning. The 
first byte is numbered 0. 

If a process attempts to write data past the Physical End of File on a disk 
file, the Operating System automatically allocates enough additional space to 
contain the data. This new space, may not be contiguous with the previous 
blocks. You can use the ALLOCATE call to ensure that any newly allocated 
blocks are located next to each other, although they may not be located near 
the rest of the file. 

READJDATA from a pipe that does not contain enough data to satisfy Count 
suspends the calling process until the data arrives in the pipe. If there are no 
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writers, the encl-of-flle indication (error 848) is returned in Ecode, Because 
pipes are circular, WRITEJ3ATA to a pipe witn insufficient room suspends tne 
calling process (tne writer) until enougn space is available (until tne reader 
has consumed enougn data). If no process nas tne pipe open for reading and 
there is not enough space in tne pipe, the end-of-file indication (848) is 
returned in Ecode. 

NOTE 

RE/\D_DATA from the MAINCONSOLE or ALTCONSOLE devices must 
specify Count - 1. 

The following program copies a file. Note that you must supply the correct 
location for Syscall in the second line of the program. 

PROGRAM CopyFile; 

USES (*Syscall.Obj*) SysCall; 

TYPE By te=-128..127; 

VAR 01dFile,Ne«File:PathName; 

OldRef Num. NeiRefNum: INTEGER; 

BytesRead. Bytesiritten :L0NGINT; 

ErrorCode: INTEGER; 

Response :CHAR; 

Buffer:ARRAY [0..511] OF Byte; 
BEGIN 
•RITE('File to copy: '); 
READLN(OldFile); 

OPEN(EirorCode,01dFile.01dRefNum. [DRead]); 
IF (Errorcode>0) THEN 
BEGIN 

HRITELN('Error '.ErrorCode,' while opening '.OldFile); 

EXIT(CopyFile); 
END; 

WRITE('Ne» file name: *); 
REAOLN(NeHFlle); 
HAKE FILE(EirorCode.NeipFile,0); 
OPENrErrorCode, NeuFile, NewRefNum. [DVrite ] ); 
REPEAT 

READ_DATA( ErrorCode, 
OldRefNum, 
ORDA(aBuffer), 

312. BytesRead. Sequential. 0); 
IF (ErrorCode=0) AND (BytesRead>0) THEN 
«RITE_DATA (ErrorCode, 
NeuRefNum 

0RD4(iBuffer), 

BytesRead, Bytesiritten, Sequential. 0); 
UNTIL (BytesRead=0) OR (Bytesiritten=0) OR (ErrorCode>0); 
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IF (ErrorCode>0) then 

¥RITELN('File copy encountered error '^ErrorCode); 
CLOSE_0BJECT(ErrorCode # NetftefNum); 
aoSE JJBJECT(ErrorCode, OldRefNura); 
END. 
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2.10.11 READLABEL and WRITE_LABEL File System calls 

REAOJ-ABEL (Var Ecode: Integer; 
Var PathrPathnarae; 
DatajVddr :Longint; 
Count :LongInt; 
Var Actual: Longlnt) 

•RI7EJLABEL (Var Ecode: integer; 
Var Path: Pathname; 

Data_Addr : Longlnt; 

Count: Longlnt; 
Var Actual :LongInt) 

Ecode: Error indicator 

Path: Name of object containing the label 

Data_Addr: source or destination of I/O 

Count: Number of bytes to transfer 

Actual: Actual number of bytes transferred 

These calls read or write the label of an object in the File System. I/O 
always starts at the beginning of the label. Count is the number of bytes the 
process wants transferred to or from Data_Addr, and Actual is the actual 
number of bytes transferred. An error is returned if you attempt to read 
more than the maximum label size, 128 bytes. 
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2.10.12 device JXNTROL File system Call 

DEVICEJMNTROL (Var Ecode: Integer; 
Var Path: Pathname; 
Var CPamuDctype) 

Ecode: Error indicator 

Path: Device to be controlled 

CParm: A record of information for the device driver 

DEVlCEjCXNTROL is used to send device-specific information to a device 
driver or to obtain device-specific information from a device driver. 

Regardless of whether you are setting device-control parameters or requesting 
information you always use a record of type Dctype. The structure of Dctype 
is: 

Dctype = RECORD 

dcversion: INTEGER; 

decode: INTEGER; 

dCData: ARRAY[0..9] OF LONGINT 

END; 

dcversion: currently 2 

decode: control code for device driver 

dcData: specific control or data parameters 

2.10.12.1 Setting Device-Control Information 

Before you use a device, you call DEVICEjCGNTROL to set the device driver. 
Once you begin using the device, you call DEVICE jCONTROL as necessary. 

Table 2-1 shows which groups of device-control functions must be set before 
using each type of device. Table 2-2 shows which characteristics are 
contained in each group. For example, you must set Group A for RS-232 
Input. As you see in Table 2-2, Group A indicates the type of parity used 
with the device. Each group requires a separate call to DEVlCE_CClNTRfJL, 
and you can set only one characteristic from each group. If you set more 
than one from the same group for a particular device, the last one set will 
apply. 
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Table 2-1 

DEVICE_CONTROL Functions Required 

before Using a Device 



Device Type 


Device Name Required Groups 


Serial RS-232 for 
input 


RS232A or RS232B 


K C, D y E, F, G 


Serial RS-232 for 
output or printer 


RS232A or RS232B 


A, B. C, GL H, I 


ProFile 


SLOTxCHANy (where 
x and y are numbers) 
or PARAPORT 


J 


Parallel printer 


SLOTxCHANy (where 
x and y are numbers) 
or PARAPORT 


I 


Console screen and 
keyboard 


NAINCONSOLE or 
ALTCONSOLE 


I 


Diskette drive 


UPPER or LOWER 


J 



Here is a sample program that shows how a device-control parameter is set. 
This program sets the parity attribute for the RS232B port to "no parity." 
Note that the parity attribute requires only that you set cparradccode and 
cparradcdata[0]. Other parameters require that you also set cparradcdatafl] 
and cparradcdata[2j They are set in a similar manner. 

VAR 

cparm: dctype; 
errnum: integer; 
path: pathname; 

BEGIN 

path: = , -RS232B'; 

cparm.dcversion:=2; (* always set this value *) 

cparm. decode := 1; 

cparm.dcdata[0]:= 0; 

DEVICE_CONTROL(ermuHi path, cparm); 
END; 
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Table 2-2 shows how to set cparmdccode, cparm.dcdata[0], cparrRdcdata[lJ, 
and cpanadcdata[2] for the various available attributes. Note that any values 
In cpaimdcdata past cparm.dcdata[2] are Ignored when you are setting 
attributes documented here. 

Table 2-2 
DEVICE_C0NTR0L Output Functional Groups 

FUNCTION .decode .dcdatafol .dcdatattl .dcdatafel 

Group A— Parity: 

No parity l 
Odd parity, no 1 l 

input parity 

checking 
Odd parity, 1 2 

input parity 

errors = 00 
Even parity, no 1 3 

input parity 

checking 
Even parity, 1 4 

input parity 

errors = $80 

Group B— Output Handshake: 
None 11 

DTR handshake 2 
xon/xoff handshake 3 
delay after cr, \J 4 ms delay 



Group c— Baud rate: 



baud 



Group D— Input waiting during Read_Data: 
wait for Count bytes 6 ~"o 
return whatever ree'd 6 l 

Group E— Input handshake: 

no handshake 7 

9 -1 -1 32767 

DTR handshake 7 

XON/XOFF handshake 8 
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Table 2-2 


(continued) 






FUNCTION .decode 


.dcdatafol 


.dcdatafll 


.dcdatafcl 


Group F— Input typeahead buffer 


: 






flush only 9 
flush and re-size 9 
flush, re-size, 9 
and set threshold 


-1 

bytes 
bytes 


-2 
-2 

low 


-2 
-2 

hi 


Group G~Disconnect Detection: 








none 10 
BREAK detected 10 
means disconnect 







non-zero 


— 


Group H--Timeout on output (handshake interval): 




no timeout 12 
timeout enabled 12 



seconds 


-- 


— 


Group I~Automatic linefeed insertion: 






disabled 17 
enabled 17 



1 


__ 


— 



Group J--Disk errors (set to l to enable, to to disable): 
enable sparing 21 sparing rewrite reread 

Group K--Break command (never required ~ available only on serial 

RS-232 devices): 



send break 13 


millisecond 
duration 





~~ 


send break 13 


millisecond 


l 


— 


while lowering DTR 


duration 







Using Group c, you can set baud to any standard rate. However, 3600, 7200, 
and 19200 baud are available only on the RS232B port. 

"Low" and "Hi" under Group F set the low and high threshold in the typeahead 
input buffer. When "Hi" or more bytes are in the input buffer, XOFF is sent 
or DTR is dropped. When "Low" or fewer bytes are in the typeahead buffer, 
X0N is sent or DTR is reasserted. The size of the typeahead buffer (bytes) can 
be any value between and 1024 bytes inclusive. 

In Group J, enabling disk sparing permits the device driver to relocate blocks 
of data from areas of the disk that are found to be bad. Enabling disk rewrite 
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permits the Operating System to rewrite data that It had trouble reading. Out 
finally managed to read. This condition is referred to as a soft error 
Enabling disk reread tells the Operating System to read data after they are 
written to make certain that they were written correctly. 

When sending a break command, as shown in Group K, any device control from 
Group A removes the break condition even if the allotted time has not yet 
elapsed. Also, sending a break will disrupt transmission of any other character 
still being sent, if you want to make certain that enough time has elapsed for 
the last character to be transmitted, call WRITE_DATA with a single null 
character (equal to 0) just prior to calling DEVICE JDCNTROL to send the break. 

Table 2-3 gives a list of mnemonic constants that you can use in place of 
explicit numbers when setting Decode. These mnemonics are provided for 
convenience. 

Table 2-3 
Decode Mnemonics 



Decode 


Mnemonic 


l 


dvParlty 


2 


dvOutDTR 


3 


dvOutxON 


4 


dvOutDelay 


5 


dvBaud 


6 


dvInWait 


7 


dvlnDTR 


8 


dvInXON 


9 


dvTypeahd 


10 


dvDlscon 


11 


dvOutNoHS 


12 


no mnemonic 


13 


no mnemonic 


15 


dvErrStat 


16 


dvGetEvent 


17 


dvAutoLF 


20 


dvDiskStat 


21 


dvDiskSpare 



2.10.12.2 Obtaining Device-Control Information 

To use DEVICEjCXNTROL to find out about the current state of a particular 
device, simply give the pathname for the particular device along with a 
function code for the type of information you need. The record of type Dctype 
that you supply is returned filled with information. 
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There are three types of Information requests you can make. Note that each 
type applies only to some of the available devices. The request types and the 
returned information are described in Table 2-4. 

Table 2-5 shows the error code provided in response to a Dccode-15 
information request. This code is given in cpanadcdats[(Q. The code, a long 
integer, is shown in Table 2-5; the bits and bytes are numbered from the right, 
counting from 0, as shown in Figure 2-1. The meaning assigned to the bit 
applies If the bit is set (equals 1). 



byte 3 



byte 2 



bytei 



byte 



7. 



o 7. 



7. 



Figure 2-1 
Disk Hard Error Codes 

Here is a program fragment that uses DEVICEjCONTROL to get information 
about the upper diskette drive. 

VAR 

cpem: dctype; 

ermum: INTEGER; 

path: pathname; 
BEGIN 

path:-' -UPPER'; 

cpan>.dcversion:-2; (• always set this value *) 

cpam.dccode := 20; 

DEVICE_C0NTR0L(ermuit path, cparn); 

ilTH cpam DO 

VRITELN (dcdata[OLd(Jdala[l3.dcdata[2Ldcdata[33, 
dcdata[4tdcdata[5Ldodata[6]> 
END; 
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Table 2-4 
Device Information 



Decode Devices 



Returned in Dcdata 



15 



Profiles 



16 



Console Screen 
and Keyboard 



[0] contains disk error status on 

last hardware error (see Table 

2-5) 

[1] contains error retry count 

since last system boot 

[0] contains numbers 0-10, 
which indicate events: 

= no event 

1 = upper diskette inserted 

2 = upper diskette button 

3 = lower diskette inserted 

4 = lower diskette button 

6 = mouse button down 

7 = mouse plugged in 

8 = power button 

9 = mouse button up 
10 = mouse unplugged 

[1] contains the current state of 
certain keys, indicated by set 
bits (if the bit is 1, the key is 
pressed) (bits are numbered from 
the right) 

= caps lock key 

1 = shift key 

2 = option key 

3 = command key 

4 = mouse button 

5 = auto repeat 

[2] contains X and Y coordinates 

of mouse, X in left 2 bytes, Y in 

right 2 bytes 

[3] contains timer value in 

milliseconds 
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Decode Devices 



Table 2-4 (continued) 

Returned in Dcdata 



20 ProFile or 

Diskette Drive 



[0] contains: 

= no disk present 

1 = disk present (but not 

accessed yet) 
The following indicate that a 
disk is present and has been 
accessed at least once. 

2 = bad block track appears 

unformatted 

3 = disk formatted by some 

program other than the 
Operating System 

4 « OS-formatted disk 
[1] contains: 

= no button press pending 

1 = button press pending, 

disk not yet ejected 
[2] contains number of available 

spare blocks, 0-16, 

meaningful only when 

Dcdata[0] = 4 and for a 

diskette 
[3] contains: 

= both copies of the 

bad-block directory OK 

1 = one copy is corrupt 

(meaningful only when 
Dcdata[0] = 4) 
[4] contains: 

= sparing disabled 

1 = sparing enabled 
[5] contains: 

= rewrite disabled 

1 = rewrite enabled 
[6] contains: 

= reread disabled 

1 = reread enabled 
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Table 2-5 
Disk Hard Error Codes 

Byte 3 

7 ■ ProFile received <> 55 to its last response 

6 = Write or write/verify aborted because more than 532 bytes of 

data were sent or because ProFile could not read its spare 
table 

5 = Host's data is no longer in RAM because ProFile updated its 

spare table 

4 = SEEK ERROR ~ unable in 3 tries to read 3 consecutive headers 

on a track 

3 = CRC error (only set during actual read or verify of 

write/verify, not while trying to read headers after seeking) 

2 = TIHEOUT ERROR (could not find header in 9 revolutions)-- not 

set while trying to read headers after seeking 

1 = Not used 

= Operation unsuccessful 

Byte 2 

7 = SEEK ERROR ~ unable in l try to read 3 consecutive headers 

on a track 

6 = spared sector table overflow (more than 32 sectors spared) 

5 » Not used 

4 = Bad block table overflow (more than 100 bad blocks in table) 

3 » ProFile unable to read its status sector 

2 * Sparing occurred 

1 = seek to wrong track occurred 

= Not used 

Byte l 

7 = ProFile has been reset 

6 - Invalid block number 

5 = Not used 

4 = Not used 

3 * Not used 

2 - Not used 

1 * Not used 
* Not used 

Byte 

This byte contains the number of errors encountered when rereading a 
block after any read error. 
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2.1Q.13 ALLOCATE File System Call 

ALLOCATE (Var Ecoderlnteger; 
RefNui: Integer; 
Contiguous : Boolean; 
Count :Longint; 
Var Actual -.Integer) 

Ecode: Error indicator 

RefNum: Reference number of object to be allocated space 

Contiguous: True = allocate contiguously 

Count: Number of blocks to be allocated 

Actual: Number of blocks actually allocated 

Use ALLOCATE to Increase the space allocated to an object If possible, 
ALLOCATE adds tne requested number of blocks to the space available to the 
object referenced by RefNum. The actual number of blocks allocated is 
returned in Actual if contiguous is true, the new space is allocated in a 
single, unfragmented space on the disk. This space is not necessarily adjacent 
to any existing file blocks. 

ALLOCATE applies only to objects on block-structured devices. An attempt to 
allocate more space to a pipe is successful only if the pipe's read pointer is 
less than or equal to its write pointer. If the write pointer has wrapped 
around but the read pointer has not, an allocation would cause the reader to 
read Invalid and uninitialized data, so the File System returns error 1186 in 
this case. 
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2.10.14 COMPACT File System Call 

COMPACT (Var Ecode: Integer; 
RefNuro: Integer) 

Ecode: Error Indicator 

RefNum: Reference number of object to be compacted 

COMPACT changes the Physical End of File to deallocate any blocks after the 
block that contains the Logical End of File for the file referenced by RefNum. 
(See Figure 2-1.) COMPACT applies only to objects on block-structured 
devices. As In the case of ALLOCATE, compaction of a pipe is legal only if 
the read pointer is less than or equal to the write pointer. If the write pointer 
has wrapped around, but the read pointer has not, compaction could destroy 
data in the pipe. The File System returns error 1188 in this case. 
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2.10.15 truncate File System call 

TRUNCATE (Var Ecode : Integer; 
RefNum: Integer) 

Ecode: Error indicator 

RefNum: Reference number of object to be truncated 

TRUNCATE sets tne Logical End of File indicator to the current position of 
the file marker. Any data beyond the file marker are lost TRUNCATE 
applies only to block-structured devices. Truncation of a pipe can destroy 
data that have been written but not yet read. As the diagram shows, 
TRUNCATE changes only LEOF. COMPACT, on the other hand, changes only 

PEOF. 



r 



TRUNCATE- 



new 
LEOF 

t 



COMPACT - 



new 
PEOF 



mmm. 



i:?: ; ;^fP9: 
At^#p3 



File Marker 



old 
LEOF 



old 
PEOF 



Figure 2-2 
The Relationship of COMPACT and TRUNCATE 

In this figure the boxes represent blocks of data Note that LEOF can point to 
any byte in the file but PEOF always points to a block boundary. Therefore, 
TRUNCATE can reset LEOF to any byte in the file, but COMPACT can reset 
PEOF only to a block boundary. 
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2.10L16 flush File System call 

FLUSH (Var Ecode: Integer; 
RefNumrlnteger) 

Ecode: Error indicator 

RefNum: Reference number of destination of I/O 

FLUSH forces all buffered Information destined for the object Identified by 
RefNum to be written out to that object 

A side effect of FLUSH Is that all FS Duffers and data structures are flushed 
(as well as the control Information for the referenced file)* If RefNum Is -l, 
only the global File System Is flushed. This is a method by which an 
application can ensure that the File System is consistent 
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2.1M7 set_safety File system call 

SET_SAFETY (Var Ecode .-Integer; 
Var PathrPathnaie; 
on_off: Boolean) 

Ecode: Error indicator 

Path: Name of object containing safety switch 

OnjDff : Set safety snitch: 

On » true 

Off = false 



Each object in the File System has a "safety switch" to help prevent accidental 
deletion. If the safety switch is on, the object cannot be deleted. 
SETJSAFETY turns the switch on or off for the object identified by path. 
Processes that are sharing an object should cooperate with each other when 
setting or clearing the safety switch. 
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2.10.18 SET_WORKING_DIR and GET_WCRKINQ_DIR File System Calls 

SETJHRKINGJHR (Var Ecode: Integer; 
var Path -.Pathname) 

GETJHRKINGJHR (Var Ecode: Integer; 
Var Path: Pathname) 

Ecode: Error Indicator 
Path: Working directory name 

The Operating system uses the working directory name to resolve partially 
specified pathnames into complete pathnames. GET_WORKING_DIR returns the 
current working directory name in Path. SET_WORKING_DIR sets the working 
directory name. 

The following program fragment reports the current name of the working 
directory and allows you to set it to something else: 

VAR iorkingDir: Pathname; 

ErrorCoderlNTEGER; 
BEGIN 

GET JHWaNG_DlR(ErrorCode, workingDir); 

IF (ErrorCodeoO) THEN 
•RITELN( 'Cannot get the current working directory!') 

ELSE •RITELNCThe current working directory is: MtorkingDir); 

•RITE ('New working directory name: '); 

READLN(VorklngDlr); 

SET_wTJRiaNG_DIR(ErrorCode, wdrkingpir); 
END; 
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2.10.19 RESET_CATALOG and GET_NEXT_ENTRY File System Calls 

RESET_CATAL0G (Var Ecode: INTEGER; 
Var Path:Pathname) 

GET_NEXT_ENTRY (Var ECOde: INTEGER; 
Var Prefix 

Entry :E_Name) 

Ecode: Error indicator 

Path: working directory name 

Prefix: Beginning of file names returned 

Entry: Names from catalog 

RESETjCATALOG and GET_NEXT_ENTRY give a process access to catalogs. 
RESETjCATALOG sets the catalog file marker to the beginning of the catalog 
specified by Path. Path should he a root volume name. GET_NEXT_ENTRY 
then performs sequential reads through the catalog file specified In the 
RESETjCATALOG call and returns File System object names. An end-of-file 
error code (848) is returned when GETjvEXT_ENTRY reaches the end of the 
catalog. If Prefix is non-null, only those entries in the catalog that begin with 
that prefix are returned. If Prefix Is "AB'V for example, only file names that 
begin with "AB" are returned. The prefix and catalog marker are local to the 
calling process, so several processes can simultaneously read a catalog without 
affecting each other. 
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2.1020 mount and unmount File system cam 

MOUNT (Var Ecoderinteger; 
Var VNamerE Name; 
var Password:E_Nan>e 
var Devname rEJtane) 

UNMOUNT (Var Ecoderinteger; 
Var vnamerE_name) 

Ecode: Error indicator 

Vname: Volume name 

Password: Password for device (currently ignored) 

Devname: Device name 

MOUNT and UNMOUNT handle access to sequential devices or block-structured 
devices. For block-structured devices, MOUNT logically attaches the volume's 
catalog to the File System. The name of the volume mounted is returned in 
the vname parameter. 

UNMOUNT detaches the specified volume from the File System No object on 
that volume can be opened after UNMOUNT has been called. The volume 
cannot be unmounted until all the objects on the volume have been closed by 
all processes using them 

Devname is the name of the device on which a volume is being mounted. 
Devname should be given without a leading dash (-). 

vname is the name of the volume that was successfully mounted, and is 
returned. 
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A process is an entity in the Lisa system that performs work. When you ask 
the Operating System to run a program, the OS creates a specific instance of 
the program and its associated data That instance is a process. 

The Lisa can have a number of processes at any one time; they appear to be 
running simultaneously. Although processes can share code and data, each 
process has its own stack. 

Only one process at a time can use the CPU. The Scheduler determines 
which process is active at a particular time. The Scheduler allows each 
process to run until some condition that would slow execution occurs (an I/O 
request, for example). At that time, the running process is saved in its 
current state. The Scheduler then checks the pool of ready-to-run processes. 
When the original process later resumes execution, it picks up where it left 
off. 

The process scheduling state has three possibilities. A running process is 
actually executing instructions. A ready process is ready to execute but is 
being held back by the Scheduler. A blocked process is ignored by the 
Scheduler. It cannot continue its execution until something causes it to 
become ready. Processes commonly become blocked while awaiting 
completion of I/O, although there are a number of other likely causes. 
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3.1 Process Structure 

A process can use up to 16 data segments and 106 code segments. 

The layout of the process address space for user processes is shown in Figure 
3-1. 
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LDSN 16 
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Shared Intrinsic Unit Data 

Screen 

Reserved 

Reserved 



Figure 3-1 
Process Address Space Layout 

Each process has an associated priority, an integer between l and 255. The 
Scheduler usually executes the highest-priority ready process. The higher 
priorities (226 to 255) are reserved for the Operating System. 

3.2 Process Hierarchy 

When the system is first started, several system processes exist At the base 
of the process hierarchy, shown in Figure 3-2, is the root process, which 
handles various internal Operating System functions. It has at least two sons: 
the Memory Manager process and the shell process. 

The Memory Manager process handles code and data segment swapping. 
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The shell process is a user process that is automatically started when the OS 
Is Initialized. It Is typically a command interpreter, but it can be any 
program. The OS simply looks for the program called SYSTEM.SHELL and 
executes it 



Root Process 




Memory Manager 

Process 

User 

Process 



Other User Processes 



Other 



Figure 3-2 
Process Tree 

Any other system process (the network control process, for example) is a son 
of the root process. 

33 Process Creation 

When a process is created, it is placed in the ready state with a priority equal 
to that of the process that created it All the processes created by a given 
process can be thought of as existing in a subtree. Many of the process 
management calls affect the entire subtree of a process as well as the process 
itself. 

3.4 Process Control 

Three system calls are provided for explicit control of a process. These calls 
allow a process to kill, suspend (block), or activate any other user process in 
the system, as long as the process identifier is known. Process-handling calls 
are not allowed to control Operating System processes. 

33 Process Scheduling 

Process scheduling is based on the priority established for the process and on 
requests for Operating System services. 

The Scheduler generally executes the highest-priority ready process. Once a 
process is executing, it loses the CPU only under certain circumstances. The 
CPU is lost when there is some specific request for the process to wait (for 
an event, for example), when there is an I/O request, or when there is a 
reference to a code segment that is not in memory. A process that makes 
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any Operating System call may lose the CPU. The process gets the CPU back 
when the Operating System is finished, except under the following conditions: 

• The running process requests input or output. The Scheduler starts the 
next highest-priority process running while the first process waits for the 
I/O to complete. 

• The running process lowers its priority Delow that of another ready process 
or sets another process's priority higher than its own. 

• The running process explicitly yields the CPU to another process. 

• The running process activates a higher-priority process. 

• The running process suspends itself. 

• A higher-priority process becomes ready. 

• The running process needs code to be swapped into memory. 

• The running process executes an event-wait call. 

• The running process calls DELAY_TIME. 

Because the Operating System cannot seize the CPU from an executing 
process except in the cases noted above, background processes should be 
liberally sprinkled with YIELD_CPU calls. 

When the Scheduler is invoked, it saves the state of the current process and 
selects the next process to run by examining the pool of ready processes. If 
the new process requires that code or data be loaded into memory, the 
Memory Manager process is launched. If the Memory Manager is already 
working on a process, the Scheduler selects the highest priority process in the 
ready queue that does not need anything swapped. 

3.6 Process Termination 

A process terminates under one of the following conditions: 

It calls TERMINATE_PROCESS. 

It reaches an 'END.' statement 

It is referred to in a K1LL_PR0CESS call. 

Its father process terminates. 

It runs into an abnormal condition. 

When a process begins to terminate, a SYS_TERMINATE exception condition is 
signaled to the terminating process and all of the processes it has created. 
By means of the DECLARE_EXCEP_HDL call (described in Chapter 5), any 
process can create an exception handler to catch the terminate exception and 
clean up before terminating. The SYS_TERMINATE exception handler will be 
executed only once. If an error occurs while the handler is executing, the 
process terminates immediately. 
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A process can call K1LL_PR0CESS on any user process whose Procjd Is 
known. TERMINATE_PROCESS, on the other hand, terminates the process that 
called it (and its descendants). TERMINATE_PROCESS also allows an event to 
be sent to the father of the terminating process if a local event channel was 
specified in the make_process call. 

Termination involves the following steps: 

1. Signal the SYS_TERM1NATE exception on the terminating process. 

2. Execute the user's exception handler, if any. 

3. Instruct all sons of the current process to terminate. 

4. Close all open files, data segments^pipes, and event channels left open by 
the user process. 

5. Send the SYS_SON_TERM event to the father of the terminating process 
if a local event channel exists. 

6. Wait for all the sons to finish termination. 

3.7 A Process-Handling Example 

The following programs illustrate the use of many of the process-management 
calls described in this chapter. The program Father, below, creates a son 
process and lets it run for a while. It then gives the user a chance to 
activate, suspend, kill, or get information about the son. 

PROGRAM Father; 

USES (*$U Source .-SysCall. Ob j*) SysCall; 

VAR ErrorCode : INTEGER; (*error returns from system calls 
proc_id:LONGINT; (* process global identifier 
progname: Pathname; (* program file to execute 
null:NameString; (* program entry point 

Info_Rec:ProcInfoRec; (* information about process 
i .-INTEGER; 
Answer: CHAR; 
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BEGIN 

ProgName^'SON.OBJ'; (* this program is defined below**) 

Null:="; 

MAKE_PROCESS(ErrorCode, ProcJEd, ProgName, Null. 0); 

IF (Errorcode<>0) THEN 

VRITELNC Error '„ErrorCode, ' during process management.'); 
FOR i:=i TO 15 DO (* idle for awhile «) 

BEGIN 

•RITELNC Father executes for a moment."); 

YIELO_CPU(ErrorCode # FALSE); (* let son run *) 
END; 

•RITECK(ill S(uspend A(ctivate I(nfo'); 
READLN(Answer); 
CASE Answer OF 

■KVk': KlLLJ'ROCESS(ErrorCode.Proc_ld); 

'SVs': SUSPEND_PROCESS(ErrorCode,Proc_Id,TRUE (* suspend 

family *)); 

'A', 'a': ACnVATEJ>ROC£SS(EiTorCocle,ProcJM,TRUE (* activate 

family *)); 

"IVi*: BEGIN 

INFO_PROCESS(ErrorCode. Proc_Id„ Inf o_Rec); 

•RITELNCSon"s name is Mnfo_Rec.ProgPathName); 

END; 
END; 
IF (ErrorCodeoO) THEN 

•RITELNC Error , ,ErrorCode„ ' during process management. '); 

END. 

The program Son is: 

PROGRAfl Son; 

USES (*$U Source:SysCall.Obj») SysCall; 

VAR ErrorCoderlNTEGER; 

null:NameString; 
BEGIN 

WHILE TRUE DO 
BEGIN 

VRITELNC Son executes for a moment.'); 
YlELD_CPU(ErrorCode. FALSE); (*let father process run*) 

END; 
END. 



3-6 



Operating System Reference Manual Processes 

3.8 Process system Calls 

This section describes the operating System calls that pertain to process 
control. A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in process-control calls: 

Pathname = STRING[255]; 

Namestring = STRING[20]; 

P_s_eventblock = *s_eventblock; 

Sjeventblock = T_event_text; 

T_event_text = array [0..slze_etext] of longint; 

Proclnf oRec = record 

progpathname : pathname; 

global_id : longint; 

father_id : longint; 

priority : 1..255; 

state : (pactive, psuspended, pvaiting); 

data_in : boolean 

end; 
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3.8.1 m/\ke_process Process system Call 

HAKE_PROCESS (Var ErrNum: Integer; 
Var Proc_Id:LongInt; 
Var ProgFile :Pathname; 

Var EntryName :NameString; (* NaineString = STRING[20] ») 
Evnt_Chn_Ref Num: Integer ) 

ErrNum: Error indicator 

Proc_Id: Process identifier (globally unique) 

ProgFile: Process file name 

EntryName: Program entry point 

Evnt_Chn_RefNum: Communication channel between calling 
process and created process 

A son process is created when another process, the father process, calls 
MAKE_PROCESS, The son process executes the program identified by the 
pathname in ProgFile. If ProgFile is a null character string, the program name 
of the father process is used. A globally unique identifier for the son process 
is returned in Procjd. 

Evnt_Chn_RefNtfn is a local event channel supplied by the father process. 
Event channels are discussed in Chapter 5. The Operating System uses the 
event channel identified by Evnt_Chn_RefNum to send the father process 
events regarding the son process (for example, SYS_SON_TERM). If 
Evnt_Chn_RefNum is zero, the father process is not informed when such 
events are produced. 

EntryName, if non-null, specifies the program entry point where execution is 
to begin. Because alternate entry points have not yet been defined for 
Pascal, this parameter is currently ignored. 

Any error encountered during process creation is reported in ErrNum 
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3.8.2 terminate_process Process System Call 

TERMINATE_PROCESS(Var ErrNum: Integer; 

Event_Ptr : P_s_eventblk) 

ErrNum: Error indicator 

Event_Ptr: Information sent to process's creator 

A process can be ended by TERM1NA7E_PR0CESS. mis call causes a 
SYS_TERMINATE exception to be signaled for the calling process and for all 
of the processes it has created. The process can declare its own 
SYSJTERM1NATE exception handler to handle whatever cleanup it needs to do 
before it is actually terminated by the system. When the terminate exception 
handler is entered, the exception information block contains a longlnt that 
describes the cause of the process termination: 

Excep_Data[0] - Process called TERM1NATE_PR0CESS. 

1 Process executed the 'END.' statement. 

2 Process called KILL_PROCESS on itself. 

3 Some other process called K1LL_PR0CESS on the 
terminating process. 

4 Father process is terminating. 

5 Process made an invalid system call (that is, an 
unknown call). 

6 Process made a system call with an invalid ErrNum 
parameter address. 

7 Process aborted due to an error while trying to swap 
in a code or data segment 

8 Process exceeded its maximum specified stack size. 

9 Process aborted due to possible lockup of the system 
by a data space exceeding physical memory size. 

10 Process aborted due to a parity error. 

There are an additional twenty-six errors that can be signaled. The entire list 
is shown at the beginning of Appendix A. 

If the terminating process was created with a communication channel, a 
SYS_S0N_TERM event is sent to the terminating process's father. The 
terminating process can specify the text of the SYS_S0N_TERM with the 
Event_Ptr parameter. Note that the first (O'th) longint of the event text is 
reserved by the system. When the event is sent to the father, the OS places 
the termination cause of the son process in the first longlnt This is the same 
termination cause that was supplied to the terminating process itself in the 
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SYS_TERMINATE exception Information block. Any user-supplied data in the 
first longint of the event text is overwrittea 

If a process specifies an event to be sent in the TERMINATE_PROCESS call 
but tne process was created without a local event channel, no event is sent to 
the father. 

If the process was created with a local event channel, an event is sent to the 
father if the process calls TERMlNATE_PROCESS with a nil Event_Ptr or if 
the process terminates by a means other than calling TERMlNATE_PROCESS. 
The event contains the termination cause in the first longint and zeroes in the 
remaining event text 

P_s_eventblk is a pointer to sjaventblk, defined as: 

CONST size_etext * 9; (• event text size - 40 bytes *) 
TYPE t_event_text = ARRAY [0..slze_etext] OF Longint; 
s__eventblk = t_event_text; 

If a process calls TERMINATE_PROCESS twice, the Operating System forces it 
to terminate even if it has disabled the terminate exception. 
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3.8.3 INFO_PROCESS Process System Call 

INF0_PR0CESS (Var ErrNum: Integer; 
PToc_Id:Longlnt; 
Var Proc_Info:ProcInfoRec); 

ErrNum: Error indicator 

Proc_Id: Global identifier of process 
Proc_Info: Information about the process identified by 
Proc_Id 

A process can call INFO_PROCESS to get a variety of information about any 
process known to the Operating System. Use the function MY_ID to get the 
Procjd of the calling process. 

ProcInfoRec is defined as: 

TYPE ProcInfoRec = RECORD 



ProgPathname 


•Pathname; 


Global id 


Longint; 


Priority 


1..255; 


State 


(PActive, PSuspended, Piaiting); 


Data in 


Boolean 


END; 





Datajn indicates whether the data space of the process is currently in 
memory. 

The procedure on the next page gets information about a process and displays 
some of it. 
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PROCEDURE Display_Info(PTOC_Id:L0NGINT); 
VAR ErrorCode : INTEGER; 

Inf o_Rec : Proclnf oRec; 
BEGIN 

INFO_PROCESS(ErrorCode. Proc_IO, Inf o_Rec); 
IF (ErrorCode=100) THEN 

WRITELNC Attempt to display info about nonexistent 
process.') 
ELSE 
BEGIN 

*ITH Infojtec DO 
BEGIN 

HRITELN(* program name: ',ProgPatnName); 
¥RITELN(' global id: ',Global_id); 
«RITELN(* priority: ', priority ); 
•RITEC state: '); 
CASE State OF 

PActive : «RITELN( * active ' ); 
PSuspended: «RITELN(' suspended'); 
Piaiting : «RITELN( ' waiting ' ) 
END 
END 
END 
END; 
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3.8.4 KILL_PROCESS Process System Call 

KILL_PROCESS (Var ErrNum : Integer; 
Proc_Id:LongInt) 

ErrNum: Error indicator 
Proc_Id: Process to be killed 

KILL_PROCESS kills the process referred to by Proc_Id and all of the 
processes in its subtree. The actual termination of the process does not occur 
until the process is in one of the following states: 

• Executing in user mode. 

• Stopped due to a SUSPEND_PROCESS call. 

• Stopped due to a DELAYJIME call. 

• Stopped due to a WAIT_EVENT_CHN or SENDJEVENT_CHN call, or 
READJDATA or WRITEJDATA to a pipe. 
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3.8.5 SUSPEhDJ^OCESS Process System Call 

SUSPEM)_PROCESS (Var ErrNum : Integer; 
Proc_Id:LongInt; 
Susp_Faroily : Boolean) 

ErrNum: Error indicators 

Proc_Id: Process to be suspended 

Susp_Family: If true, suspend the entire process subtree 

SUSPEND_PROCESS allows a process to suspend (block) any process in the 
system. The actual suspension does not occur until the process referred to by 
Procjd is in one of the following states: 

• Executing in user mode 

• Stopped due to a DELAY JTME call 

• Stopped due to a WAIT_EVENT_CHN call 

Neither expiration of the delay time nor receipt of the awaited event causes 
a suspended process to resume execution. SUSPEND_PROCESS is the only 
direct way to block a process. Processes, however, can become blocked during 
I/O, by the timer (see DELAY J1ME), or for many other reasons. 

If Susp_Famlly is true, the Operating System suspends both the process 
referred to by Procjd and all of its descendants. If Susp_Family is false, 
only the process identified by Procjd is suspended. 
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3.8.6 activa7E_process Process System call 

ACnVATE_PROCESS(Var ErrNun : Integer; 
Proc_Id:LongInt; 
Act_Faroily : Boolean) 

ErrNum: Error indicator 

Proc_Id: Process to be activated 

Act_Family: If true, activate the entire process subtree 

To awaken a suspended process, call ACTIVATE_PROCESS. A process can 
activate any other process in the system. Note that ACTIVATE_PROCESS can 
awaken only a suspended process. If the process is blocked for some other 
reason, ACTIVATE_PROCESS cannot unblock it. If Act_Family is true, 
ACTTVATE_PROCESS also activates all the descendents of the process referred 
to by Procjd. 
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3.8.7 SE7PRI0RITY_PR0CESS Process system Call 

SETPRIORITY_PROCESS(Var ErrNum: Integer; 

Proc_Id : Longlnt; 
Ne»_Pr ior ity : Integer ) 

ErrNum: Error indicator 
Proc_Id: Global id of process 
New_Priority: Process's new priority number 

SETPRI0RITY_PROCESS changes the scheduling priority of the process 
referred to by Procjd to New_Priority. The priority value must be between 1 
and 225. (Operating System processes execute with priorities between 226 
and 255.) The higher the priority, the more likely the process is to be allowed 
to execute. 
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3.8.8 YIELD_CPU Process System call 

YIELD_CPU(Var ErrNum: Integer; 
To_Any:Boolean) 

ErrNum: Error indication 

To_Any: Yield to any process, or only nigher or equal 
priority 

Background processes snould use YIELD_CPU often to allow other processes to 
execute when they need to. Successive yields by processes of the same 
priority result in a "round robin" scheduling of the processes. If To_Any is 
true, YIELD_CPU causes the calling process to yield the CPU to any other 
ready process. If To_/\ny is false, YIELD_CPU causes the calling process to 
give the CPU to any other ready-to-execute process with an equal or higher 
priority. If no process meets the ToAny criterion, the calling process simply 
continues execution. 
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3.8.9 MYJD Process System Call 

«Y_lD:Longint 

MYJD is a function tnat returns the unique global identifier (a longint) of tne 
calling process. A process can use MYJD to perform process handling calls 
on itself. 

For example: 

SetPrlority_Process(ErrNuntriy_ld^ 100) 

sets the priority of the calling process to 100. 
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Every process has a set of code segments and data segments which are in 
physical memory when they are used. The logical address used by the process 
must be translated into the physical address used by the memory controller. 
This function is handled by the memory management unit (MMU). 

4.1 Data Segments 

Each process has a data segment that the Operating System automatically 
allocates to it for use as a stack. The stack segment's internal structures are 
managed by the hardware and the Operating System. 

A process can acquire additional data segments for uses such as heaps and 
interprocess communication. These additional data segments can be private 
(or local ) data segments or shared data segments. Private data segments 
can be accessed only by the creating process. When the process terminates, 
any private data segments still in existence are destroyed. Shared data 
segments can be accessed by any process that opens those segments. 

The Operating System requires that data segments be in physical memory 
before the data are referenced. The Scheduler automatically loads all of the 
data segments that the program says it needs. It is the responsibility of the 
programmer to ensure that the program declares all its needs by associating 
itself with the needed data segments before they are needed. 

This process of association is called binding. A program can bind a data 
segment to itself in several ways. When a program creates a data segment by 
using the MAKE_DATASEG call, the segment is automatically opened and 
bound to the program. If a program needs to open a segment that was 
created by another program, the OPEN_DATASEG call is used. That call binds 
the segment to the calling process, as well as opening the segment for the 
process. Since there may be times when a process needs to use more data 
segments than can be bound at one time, the UNBIND_DATASEG call is 
provided to unbind the data segment without closing it. The program can then 
use BINDJDATASEG to bind another data segment to the program. 

The Operating System views all data segments except the stack as linear 
arrays of bytes. Therefore, allocation, access, and interpretation of structures 
within a data segment are the responsibility of the program. 

4.2 The Logical Data Segment Number 

The address space of a process allows up to 16 data segments bound to a 
process at the same time, in addition to the stack. Each bound data segment 
is associated with a specific region of the address space by means of a 
Logical Data Segment Number (LDSN). See Figure 3-1 for an illustration of 
the address space of a process. While a data segment is bound to the process, 
it is said to be a member of the working set of the process. 
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The process associates a data segment with a specific LDSN In the 

MAKE_DATASEG or CFEN_DATASEG call. 

The LDSN, which has a valid range of 1 to 16, is local to the calling process. 
The process uses the LDSN to keep track of where a given data segment can 
be found. More than one data segment can be associated with the same LDSN, 
but only one such segment can be bound to a given LDSN at any instant and 
thus be a member of the working set of the process. 

4.3 Shared Data Segments 

Cooperating processes can share data segments. Shared segments cannot be 
larger than 128 Kbytes in length. As with local data segments, the segment 
creator assigns the segment a File System pathname. All processes that share 
that data segment then use the same pathname. If the shared data segment 
contains address pointers to data within the segment, the cooperating 
processes must also use the same LDSN with the segment. This ensures that 
all logical data addresses referencing locations within the data segment are 
consistent for the processes sharing the segment. A shared data segment is 
permanent until explicitly killed by a process. 

4.4 Private Data Segments 

Data segments can also be private to a process. In this case, the maximum 
size of the segment can be greater than 128 Kbytes. The actual maximum 
size depends on the amount of physical memory in the machine and the 
number of adjacent LDSNs available to map the segment. The process gives 
the desired segment size and the base LDSN to map the segment. The 
Memory Manager then uses ascending adjacent LDSNs to map successive 128 
Kbyte chunks of the segment. The process must ensure that enough 
consecutive LDSNs are available to map the entire segment. 

Suppose a process has a data segment already bound to LDSN 2. If the 
program tries to bind a 256 Kbyte data segment to LDSN 1, the Operating 
System returns an error because the 256 Kbyte segment needs two consecutive 
free LDSNs. Instead, the program should bind the segment to LDSN 3 and the 
system automatically also uses LDSN 4. 

4.5 Code Segments 

Division of a program into multiple code segments (swapping units) is dictated 
by the programmer through commands to the Compiler and Linker. The MMU 
registers can map up to 106 code segments. 

4.6 Swapping 

When a process executes, the following segments must be in physical memory: 

• The current code segment 

• All the data segments in the process working set (the stack and all bound 
data segments) 

The Operating System ensures that this minimum set of segments is in physical 
memory before the process is allowed to execute. If the program calls a 
procedure in a segment not in memory, a segment swap-in request is initiated. 
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In the simplest case, this request only requires the system to allocate a block 
of physical memory and to read in the segment from the disk. In a worse 
case, the request may require that other segments he swapped out first to 
free up sufficient memory. A clock algorithm is used to determine which 
segments to swap out or replace. This process is Invisible to the program. 

4.7 Memory Management System Calls 

This section describes all the Operating System calls that pertain to memory 
management. A summary of all the Operating System calls can be found in 
Appendix A The following special types are used in memory management 
calls: 

Pathname = STRING[255]; 

Tdstype = (ds_shared„ ds_private); 

DsInfoRec - Record 

mem_size:longint; 

disc_size : longint; 

nunbjopen : integer; 

LDSN : integer; 

boundF: boolean; 

presentF : boolean; 

creatorF rbooiean; 

r waccess : boolean; 

segptr: longint; 

volname:e_name; 
end; 
E_name = string [32]; 
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4*7.1 MAKEJDATASEG Memory Management System Call 

riAKE_DATASEG (Var ErrNum: Integer; 
Var Segname :Pathname; 

Memjsize, Disk_Size:LongInt; 
Var RefNuro: Integer; 
Var SegPtr rLonglnt; 

Ldsn: Integer 

Dstype :Tdstype) 

ErrNum: Error indicator 

Segname: Pathname of data segment 

hem_Size: Bytes of memory to be allocated to data segment 

Disk_Size: Bytes on disk to be allocated for swapping segment 

RefNum: Identifier for data segment 

SegPtr Address of data segment 

Ldsn: Logical data segment number 

Dstype: Type of dataseg (shared or private) 

MAKE_DATASEG creates the data segment identified by the pathname, 
Segname, and opens it for immediate read-write access. Segname is a File 
System pathname. 

The parameter Mem_Size determines how many bytes of main memory are 
allocated to the segment. The actual allocation takes place in terms of 
512-byte pages. If the data segment is private (Dstype is ds_prlvate), 
Mem_Size can be greater than 128 Kbytes, but you must ensure that enough 
consecutive LDSNs are free to map the entire segment. 

DiskjSlze determines the number of bytes of swapping space to be allocated 
to the segment on disk. If Disk_Size is less than MemSize, the segment 
cannot be swapped out of main memory. In this case the segment is memory 
resident until it is killed or until its size in memory becomes less than or 
equal to its Dlsk_size (see SIZE_DATASEG). The application programmer 
should be aware of the serious performance implications of forcing a segment 
to be memory resident Because the segment cannot be swapped out, a new 
process may not be able to get all of its working set into memory. To avoid 
thrashing, each application should ensure that all of its data segments are 
swappable before it relinquishes the attention of the processor. 

Tt\e calling process associates a Logical Data Segment Number (LDSN) with 
the data segment. If this LDSN is bound to another data segment at the time 
of the call, the call returns an error. 

RefNum is returned by the system to be used in any further references to the 
data segment. The Operating System also returns SegPtr, an address pointer to 
be used to reference the contents of the segment. SegPtr points to the base 
of the data segment. 

Any error conditions are returned in ErrNum. 
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When a data segment Is created, it immediately becomes a member of the 
working set of the calling process. You can use UsBIND_DATASEG to free 
the LDSN. 
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4J.2 KILLJDATASEG Memory Management system Call 

KILL_DATASEG (Var ErrNum: Integer; 
var Segname:Pathname) 

ErrNum: Error indicator 

Segname: Name of data segment to be deleted 

When a process is finished with a snared data segment, it can issue a 
KILLJDATASEG call for that segment. (KILL_DATASEG cannot be used on a 
private data segment.) If any process, including the calling process, still has 
the data segment open, the actual deallocation of the segment is delayed until 
all processes have closed it (see CLOSEJDATASEG). During the interim period, 
however, after a KILL_DATASEG call has been issued but before the segment 
is actually deallocated, no other process can open that segment. 

KILLJDATASEG does not affect the membership of the data segment in the 
working set of the process. The RefNum and SegPtr values are valid until a 
CLOSEJDATASEG call is issued 

One important note: normally, when a data segment is closed, the contents 
are written to disk as a file with the pathname associated with the data 
segment. If, however, the program calls KILLJDATASEG on the data segment 
before closing it, the contents of the data segment are not written to disk and 
are lost when the segment is closed. 
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4,7.3 CPEN_DATASEG Memory Management system Call 

OPEN_DATASEG (Var ErrNum: Integer; 
Var Segname: Pathname; 
Var RefNum: integer; 
Var SegPtr:LongInt; 
Ldsn: integer) 

ErrNum: Error indicator 

Segname: Name of data segment to be opened 

RefNum: Identifier for data segment 

SegPtr Pointer to contents of data segment 

Ldsn: Logical data segment number 

A process can open an existing shared data segment with OPENJDATASEG. 
The calling process must supply the name of the data segment (Segname) and 
the Logical Data Segment Number to be associated with it. The LDSN given 
must not have a data segment currently bound to it. The segment's name is 
determined by the process that creates the data segment; it cannot be null. 

The Operating System returns both RefNum, an identifier for the calling 
process to use in future references to the data segment and SegPtr. an 
address pointer used to reference the contents of the segment. 

When a data segment is opened, it immediately becomes a member of the 
working set of the calling process. The access mode of the newly opened 
segment is Readonly. You can use SETACCESSJDATASEG to change the 
access rights to Readwrite. You can use UNBINDJDATASEG to free the 
LDSN. 

You cannot use OPEN on a private data segment, since calling CLOSE on a 
private data segment deletes it. 
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4.7.4 CLOSE_DATASEG Memory Management system Call 

CLOSE_DATASEG (Var ErrNum : Integer; 
RefNum: Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

CLOSE_DATASEG terminates any use of RefNum for data segment operations. 
If the data segment is bound to a Logical Data Segment Number, 
CLOSE_DATASEG frees tnat LDSN. The data segment Is removed from the 
working set of the calling process. RefNum is made invalid. Any references 
to the data segment using the original SegPtr will have unpredictable results. 

If RefNum refers to a private data segment CLOSE_DATASEG also kills the 
data segment deallocating the memory and disk space used for the data 
segment. If RefNum refers to a shared data segment the contents of the 
data segment are written to disk as if FLUSH_DATASEG had been called. (If 
KILL_DATASEG is called before CLOSE_DATASEG, the contents of the data 
segment are thrown away when the last process closes the data segment.) 

The following procedure sets up a heap for LisaGraf using the memory 
management calls: 

PROCEDURE InitDataSegForLisaGraf (var ErrorCode: Integer ); 

CONST HeapSize=16384; (* 16 KBytes for graphics heap *) 
DiskSize=16384; 

VAR HeapBuf :L0NGINT; (« pointer to heap for LisaGraf ») 
GrafHeap:PathName; (* data segment path name *) 

Heapjtefnum: INTEGER; (* refnum for heap data seg ») 

BEGIN 

Gr afHeap : = ' grafneap " ; 

rjPEN_rjATASEG(ErrorCode, Graf Heap, Heap_Refnum, HeapBuf, 1); 

IF (Errorcode<>0) then 

BEGIN 

WRITELNC Unable to open', Grafneap. 'Error is •, ErrorCode) 

END 

asE 

InitHeap(POINTER(HeapBuf ), POINTER(HeapBuf +HeapSize), 
aHeapError); 
END; 
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4.7.5 flush_dataseg Memory Management system Call 

FLUSH_0ATASE6 (Var ErrNum: Integer; 
RefNura:Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

FLUSH_DATASEG writes the contents of the data segment identified by 
RefNum to the disk. (Note that CLOSE_DATASEG automatically flushes the 
data segment before closing it, unless KILL_DATASEG was called first.) This 
call has no effect upon the memory residence or binding of the data segment. 
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4.7.6 SIZEDATASEG Memory Management System Call 

SIZE_DATASE6 (Var ErrNum: Integer; 

Refnum: Integer; 

DeltaMemSize -.Longlnt; 
Var NetflemSize: Longlnt; 

DeltaOiskSize : Longlnt; 
Var NewDiskSize :Longlnt) 

ErrNum: Error indicator 

RefNum: Data segment identifier 

DeltaMemSize: Amount in bytes of change in memory 

allocation 

NewMemSize: New actual size of segment in memory 

DeltaDiskSize : Amount in bytes of change in disk allocation 

NewDiskSize: New actual disk (swapping) allocation 

SIZE_DATASEG changes the memory and/or disk space allocations of the data 
segment referred to by RefNum. Both DeltaMemSize and DeltaDiskSize can 
be either positive, negative, or zero. The changes to the data segment take 
place at the high end of the segment and do not destroy the contents of the 
segment, unless data are lost in shrinking the segment. Because the actual 
allocation is done in terms of pages (512-byte blocks), the NewMemSize and 
NewDiskSize returned by SIZEJDATASEG may be larger than the old size plus 
delta size of the respective areas. 

If the NewDiskSize is less than the NewMemSize, the segment cannot be 
swapped out of memory. The application programmer should be aware of the 
serious performance implications of forcing a segment to be memory resident. 
Because the segment cannot be swapped out, a new process may not be able 
to get all of its working set into memory. To avoid thrashing, each 
application should ensure that all of its data segments are swappable before it 
relinquishes the attention of the processor. 

If the necessary adjacent LDSNs are available, SIZE_DATASEG can increase 
the size of a private data segment beyond 128 Kbytes. 
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nj.7 INFOJDATASEG Memory Management system call 

INFO_DATASEG (Var ErrNum: Integer; 
RefNum: Integer; 
Var DsInforDsInfoRec) 

ErrNum: Error indicator 

RefNum: Identifier of data segment 

Dslnfo: Attributes of data segment 

INFO_DATASEG returns information about a data segment to tne calling 
process. Tne structure of tne Dslnf oRec record is: 

RECORD 

Mem_Size:LongInt (• Bytes of memory allocated to data segment * 
Oisc_Slze:LongInt (* Bytes of disk space allocated to segment * 
NumbOpen: Integer (• Current number of processes with segment open * 
Ldsn: Integer (* LOSN for segment binding * 

BoundF: Boolean (* True if segment is bound to LDSN of calling proc * 
PresentFrBoolean (* True if segment is present in memory * 
CreatorF:Booleanm (* True if the calling process is the creator * 

(* of the segment * 

RVAccess: Boolean (* True if the calling process has Ifrite access » 

(* to segment *' 

END; 
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4.7.8 INFOJLDSN Memory Management system call 

INFO_LDSN ( Var ErrNunrlnteger; 
Ldsn: Integer; 
Var RefNuro: Integer) 

ErrNum: Error indicator 

Ldsn: Logical data segment number 

RefNum: Data segment identifier 

»>FO_LDSN returns the ref num of the data segment currently bound to Ldsn. 
You can then use INFO_DATASEG to get information about that data segment. 
If the LDSN specified is not currently bound to a data segment the refnum 
returned is -1. 
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0,7.9 INF0_ADDRESS Memory Management System Call 

INFO_ADORESS (Var ErrNura: Integer- 
Address :Longint; 
Var RefNum: Integer) 

ErrNum: Error indicator 

Address: The address about which the program needs information 

RefNum: Data segment identifier 

This call returns the refnum of the currently hound data segment that 
contains the address given. 

If no data segment that contains the address given is currently bound to the 
calling process, an error indication is returned in ErrNum. 
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47.10 MEMJNFO Memory Management system Call 

MEM_INF0 (var ErrNumrlnteger; 
Var Swapspace; 
Dataspace; 
Cur_codesize; 
Haxcodeslze : Longint ) 

ErrNum: Error indicator 

Swapspace: Amount, in bytes, of swappable system memory 

available to the calling process 
Dataspace: Amount, in bytes, of system memory that the 

calling process needs for its bound data areas, 

including the process stack and the shared 

intrinsic data segment 
Cur_codesize: Size, in bytes, of the calling segment 
Max_codesize: size, in bytes, of the largest code segment 

within the address space of the calling process 

This call retrieves information about the memory resources used by the calling 
process. 
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4.7.11 SETACCESS_DATASEG Memory Management System Call 

SETACCESS_DATASEG (Var ErrNum: Integer; 

RefNum: Integer; 
Readonly : Boolean) 

ErrNum: Error indicator 
RefNum: Data segment identifier 
Readonly: Access mode 

A process can control the kinds of access it is allowed to exercise on a data 
segment with the SETACCESSJDATASEG call. Refnum is the identifier for 
the data segment. If Readonly is true, an attempt by the process to write to 
the data segment results in an address error exception condition. To get 
readwrite access, set Readonly to false. 
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4,7.12 BIND_DATASEG and UNBIN3DATASEG Memory Management System Calls 

BIND_OATASEG(Var ErrNum: Integer; 
RefNum: Integer) 

Ut«IND_DATASEG(Var ErrNum -.Integer; 
RefNum: Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

BINDJDATASEG binds the data segment referred to by RefNum to its 
associated Logical Data Segment Numbers). UNBINDJDATASEG unbinds the 
data segment from its LDSNs. BINDJDATASEG causes the data segment to 
become a member of the current working set. At the time of the 
BIND_DATASEG call, the necessary LDSNs must not be bound to a different 
data segment. UNBIND_DATASEG frees the associated LDSNs. A reference to 
the contents of an unbound segment gives unpredictable results. 
GPEN_DATASEG and MAKEJDATASEG define which LDSNs are associated 
with a given data segment. 
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Exceptions and Events 



Processes have several ways to keep informed about the state of the system. 
Normal process-to-process communication and synchronization employ pipes, 
shared data segments, or events. Abnormal conditions, including those your 
program may define, employ exceptions (interrupts). Exceptions are signals to 
which the process can respond in a variety of ways under your control. 

5.1 Exceptions 

Normal execution of a process can be interrupted by an exceptional condition 
(such as division by zero or reference to an invalid address). Some error 
conditions are trapped by the hardware and some by the system software. The 
process itself can define and signal exceptions of your choice. 

When an exception occurs, the system first checks the state of the exception. 
The three exception states are: 

• Enabled 

• Queued 

• Ignored 

If a system-defined exception is enabled the system looks for an associated 
user-defined handler. If none is found, the system invokes the default 
exception handler, which usually aborts the process that generated the 
exception. If a user-defined exception is enabled, the system invokes the 
associated user-defined exception handler. You create a new exception by 
declaring and enabling a handler for it. 

If the state of the exception is queued the exception is placed on a queue. 
When the exception is subsequently enabled, the queue is examined and the 
appropriate exception handler is invoked. Processes can flush the exception 
queue. 

If the state of the exception is ignored the system detects the occurrence of 
the exception, but the exception is neither honored nor queued. Note that 
ignoring a system-defined exception has uncertain effects. Although you can 
cause the system to ignore even the SYS_TERM1NATE exception, that 
capability is provided so that your program can clean up before terminating. 
You cannot set your program to ignore fatal errors. 

Invocation of the exception handler causes the Scheduler to run, so it is 
possible for another process to run between the signaling of the exception and 
the execution of the exception handler. 
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52. System-Defined Exceptions 

Certain exceptions are predefined by tne Operating System. These include: 

• Division by zero (SYS_ZERO_DIV). The default handler aborts the process. 

• Value out of bounds (that is, range check error) or illegal string index 
(SYS_VALUE_OOB). The default handler aborts the process. 

• Arithmetic overflow (SYSJJVERFLOW). The default handler aborts the 
process. 

• Process termination (SYSJTERMINATE). This exception is signaled when a 
process terminates, or when there is a bus error, address error, illegal 
instruction, privilege violation, or nil emulator error. The default handler 
does nothing. This exception is different from the other system-defined 
exceptions in that the program always terminates as soon as the exception 
occurs. In the case of other (non-fatal) errors, the program is allowed to 
continue until the exception is enabled. 

Except where otherwise noted, these exceptions are fatal if they occur within 
Operating System code. The hardware exceptions for parity error, spurious 
interrupt, and power failure are also fatal. 

5.3 Exception Handlers 

A user-defined exception handler can be declared for a specific exception. 
This exception handler is coded as a procedure but must follow certain 
conventions. Each handler must have two input parameters: Environment_Ptr 
and Data_Ptr. The Operating System ensures that these pointers are valid 
when the handler is entered. Environment_Ptr points to an area in the stack 
containing the interrupted environment: register contents, condition flags, and 
program state. The handler can access this environment and can modify 
everything except the program counter, register A7, and the supervisor state 
bit in the status register. Data_Ptr points to an area in the stack containing 
information about the specific exception. 

Each exception handler must be defined at the global level of the process, 
must return, and cannot have any EXIT or global GOTO statements. Because 
the Operating System disables the exception before calling the exception 
handler, the handler should re-enable the exception before it returns. 

If an exception handler for a given exception already exists when another 
handler is declared for that exception, the old handler becomes dissociated 
from the exception. 

An exception can occur during the execution of an exception handler. The 
state of the exception determines whether it is honoredplaced on a queue, or 
ignored. If the second exception has the same name as the exception that is 
currently being handled and its state is enabled, a nested call to the exception 
handler occurs. (The system always disables the exception before calling the 
exception handler, however. Therefore, nested handler calling occurs only if 
you explicitly enable the exception.) 



5-2 



Operating System Reference Manual Exceptions and Events 

There is an exception-occurred flag, Ex_occurred_f, for every declared 
exception; it is set whenever the corresponding exception occurs. This flag 
can oe examined and reset using the INFOJEXCEP system call. Once the flag 
is set, it remains set until FLUSH_EXCEP is called. 

The following program fragment gives an example of exception handling. 

PROCEDURE Handler (Errvironment_PtRp_env_blk; 

Data_Ptnp_ex_data); 
W\R EnNurrcINTEGER; 
BEGIN 

(«Environment_Ptr points to a record containing the program *) 
("counter and all registers. Data_Ptr points to an array of 12 *) 
(*longints that contain the event header and text if this handler *) 
(*ls associated with an event-call channel (See below) *) 



ENABU£_EXC^enriurruBxcep_name); 

END; 

BEGIN ("Main program*) 



Excep_name:- , EndOfDoc , ; 
DEC^AREJEXCS^HDUerrrwfTjexcepj^ 



SlGNAL_EXCEP(eif]nrriiTiex(^jriarre^xcepjtetaX- 



At the time the exception handier is invoked for a SYSJTERMINATE 
exception, the stack is as shown in Figure 5-1. 



5-3 



Operating System Reference Manual 



Exceptions and Events 



low address 



v --* 



Link 



Program Counter 



Data Ptr 



Environment Ptr 



Terminate Flag 



Exception Kind 
Function Code (fc) 
Access Address (aa) 
Instruction Register 

Status Register 
Program Counter 



Program Counter 

Status Register 

D0-D7 and A0-A7 



Link 



Program Counter 



Exception Data Block 
(SYSJTERMINATE Exception) 



Exception Environment Block 



high address 



Figure 5-1 
Stack at Exception Handler Invocation 

The Exception Data Block given here reflects the state of the stack upon a 
SYSJTERMINATE exception. The Term_Ex_Data record (described in Appendix 
A) gives the various forms the data block can take. The Excep_Kind field (the 
first, or Oth, longint) gives the cause of the exception. The status register and 
program counter values in the data block reflect the true (current) state of 
these values. The same data in the Environment block reflects the state of 



5-4 



Operating System Reference Manual Exceptions and Events 

these values at the time the exception was signaled, not the values at the 
time the exception actually occurs. 

For SYS_ZERO_DIV, SYS_VALUE_OOB, and SYS_OVERFLOW exceptions, the 
Hard_Ex_Data record described in Appendix A gives the various forms that 
the data block can take. 

In the case of a bus or address error, the PC (program counter) can be 2 to 10 
bytes beyond the current instruction. The PC and A7 cannot be modified by 
the exception handler. 

When a disabled exception is re-enabled, a queued exception may be signaled. 
In this case, the exception environment reflects the state of the system at the 
time the exception was re-enabled, not the time at which the exception 
occurred. 

5.4 Events 

An event is a piece of information sent by one process to another, generally 
to help cooperating processes synchronize their activities. An event is sent 
through a kind of pipe called an event channel. The event is a fixed-size 
data block consisting of a header and some text. The header contains control 
information, the identifier of the sending process, and the type of the event. 
The header is written by the system, not the sender, and is readable by the 
receiving process. The event text is written by the sender; its meaning is 
defined by the sending and receiving processes. 

There are several predefined system event types. The predefined type "user" is 
assigned to all events not sent by the Operating System. 

5.5 Event Channels 

Event channels can be viewed as higher-level pipes. One important difference 
is that event channels require fixed-size data blocks, whereas pipes can 
handle an arbitrary byte stream. 

An event channel can be defined globally or locally. A global event channel 
has a globally defined pathname catalogued in the File System and can be 
used by any process. A local event enamel, however, has no name and is 
known only by the Operating System and the process that opened it Local 
event channels can be opened by user processes only as receivers. A local 
channel can be opened by the father process to receive system-generated 
events pertaining to its son. 

There are two types of global and local event channels: event-wait and 
event-call. If the receiving process is not ready to receive the event, an 
event-wait type of event channel queues an event sent to it . An event-call 
type of event channel, however, forces its event on the process, in effect 
treating the event as an exception. In that case, an exception name must be 
given when the event-call event channel is opened, and an exception handler 
for that exception must be declared. If the process reading the event-call 
channel Is suspended at the time the event is sent, the event is delivered 
when the process becomes active. 



5-5 



Operating System Reference Manual Exceptions and Events 

When an event channel is created, the operating System preallocates enough 
space to the channel for typical interprocess communication. If 
SEND_EVENT_CHN is called when the channel does not have enough space for 
the event, the calling process is blocked until enough space is freed up. 

If WAITJEVENTjCHN is called when the channel is empty, the calling process 
is blocked until an event arrives. 

The following code fragments use event-wait channels to handle process 
synchronization. Operating System calls used in these program fragments are 
documented later in this chapter. 

Process A: 



chnname := , event_chamel_r; 

exceptions "; 

receiver := TRUE; 

OPEN_EVENT_CHN (errint, chn_narae, refnuml, exception, receiver); 

chnjname := , eve^t_channel_2■; 

receiver := FALSE; 

OPEN_EVENT_CHN (errint, chnname, refnum2, exception, receiver ); 

waitlist. length := 1; 

waitlist. refnnn[0] := refnuml; 

REPEAT 

eventl_ptr A .[0] := agreedjuponjvalue; 

interval.sec := 0; (* send event immediately *) 

interval. msec := 0; 

SEND_EVENT_CHN (errint, refnunfi, eventl_ptr, interval, clktime); 

•AIT_EVENT_CHN (errint, waitlist, refnum_signaling, event2_ptr); 



(* processing performed here *) 
UNTIL AllOone; 
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Process B: 



chn_name := 'event_channel_2 , ; 

exception := "; 

receiver := TRUE; 

OPEN_EVENT_CHN (enlnt, chnjiame, ref numZ, exception, receiver); 

chnname := 'event jchanrelj.'; 

receiver := FALSE; 

OPEN_EVENT_CHN (errint, chnjrame, ref numl, exception, receiver); 

waitlist. length := l; 

waitlist. ref num[0] := ref numl; 

REPEAT 

event2_ptr A .[0] := agreed_upon_value; 

interval. sec := 0; (* send event immediately *) 

interval. msec := 0; 

iAIT_EVENT_CHN (errint, waitlist, ref num_signaling, eventl_ptr); 



(* processing performed here *) 



SEND_EVENT_CHN (errint, ref nunc event2_ptr, interval, clktime); 
UNTIL AllOone; 



The order of execution of the two processes is the same regardless of the 
process priorities. Process switch always occurs at the WAH_EVENT_CHN 
call. 

In the following example using event-call channels, process switch may occur 
at different places in the programs. Process A calls YIELDjCPU, which gives 
the CPU to Process B only if Process B is ready to run. 
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Process A: 

PROCEDURE Handler(Envj)tr:pjenvJ»lK; 
Data_ptr :p_ex_deta); 



BEGIN 

event2_ptr\[0] := agreedjuponjvalue; 

(* processing performed here •) 



Interval. sec := 0; (* send event immediately *) 
interval. msec :« 0; 

SEMD_EVENT_CHN (errlnt,refnum2,event2_ptr, interval, clktime); 
to_any :» true; 
YIELD_CPU (errlnt,to_any); 
END; 

BEGIN (• Main program**) 



DECLARE_EXCEP_HDL (errint, excep_name_l, aHandler ); 

chnname := 'event_cnamel_l*; 

exception:* excep_nanie_l; 

receiver := TRUE; 

OPEN_EVENT_CHN (errint, chnjome, ref numl, exception, receiver); 

chn_name := *eventchannei_2'; 

receiver := FALSE; 

exception := "; 

0PEN_EVENT_cHN (err int„ chn_name, ref num2, exception, receiver ); 

SEND_EVENT_CHN (errint, refruie, event2_ptr, interval, clktime); 

to_any :* true; 

YiaDjDPU (errint, to_any); 
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Process &• 

PROCEDURE Handler(Ewj>tr:p_erw_blK; 
Datajptr :p_ex_data); 



BEGIN 

event2_ptr\[0] := agreedjupon_value; 

(* processing performed here *) 



interval. sec := 0; (* send event immediately *) 
interval .msec := 0; 

SEND_EVENT_CHN ( err int. refnuml. event2_ptr. interval, clktime); 
to any := true; 
YiaD_CPU (errint.to_any); 
END; 



BEGIN (*Main program *) 

DECLARE_EXCEP_HDL (errint.excepjiamejJL.aHandler) 

cfm_nane := 'event_channel_l , ; 

exception := excep_name_l; 

receiver "= FALSE; 

exceptions "; 

0PEN_EVENT-CHN (erring chn_name. refnuml. exception, receiver); 

chn name := 'even^chame^'; 

recelver := TRUE; 

OPENJEVENTCHN (err int. chnjriame. ref num2. exception, receiver); 



END. 
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5.6 The System Clock 

A process can read the system clock time, convert it to local time, or delay 
its own continuation until a given time. The year, month, day, hour, minute, 
second, and millisecond are available from the clock. The system clock is set 
up through the Workshop shell. For more information, see the workshop user's 
Guide for the Lisa . 

5.7 Exception Managemen t System Calls 

This section describes all the Operating System calls that pertain to exception 
management A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in exception management 
calls: 

TjBX_name = STRING[16]; 

Longadr « longlnt; 

T_ex_data = Array [0..11] of longlnt; 

T_ex_sts - Record 

ex_occurred_f .-boolean; 

ex_state : t_ex_state; 

nuni_excep : integer; 

rtdl_adr: longadr; 
end; 
T_ex_state ■ (enabled, queued, ignored); 
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5.7.1 DECLARE_EXCEP_HDL Exception Management System Call 

DECLARE_EXCEP_HDL ( Var ErrNum: Integer; 

Var Excep_Name:t_ex_name; 
Entry_Point : LongAdr ) 

ErrNum: Error indicator 

Excep_Name: Name of exception 
Entry_Point: Address of exception handler 

DECLARE_EXCEP_HDL sets the Operating System so that the occurrence of 
the exception referred to by Excep_Name causes the execution of the 
exception handler at Entry_PoinL 

Excep_Name is a character string name with up to 16 characters that is 
locally defined in the process and known only to the process and the Operating 
System. If Entry_Point is nil and Excep_Name specifies a system exception, 
the system default exception handler is used. Any previously declared 
exception handler is dissociated Py this call. The exception Itself is 
automatically enabled. 

If any Excep_Name exceptions are queued at the time of the 
DECLARE_EXCEP_HDL call, the exception is automatically enabled and the 
queued exceptions are handled by the newly declared handler. 

You can call DECLARE_EXCEP_HDL with an exception handler address ofnil 
to dissociate your handler from the exception. If there is no system handler 
defined, the program that signals the exception receives an error 201. 
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5.7.2 DISABLE.EXCEP Exception Management System Call 

DISABLE_EXCEP (Var ErrNum: Integer; 

Var Excep_Name:t ex_name; 
Queue iBooleanJ 

ErrNum: Error indicator 

Excep_Name: Name of exception to be disabled 

Queue: Exception queuing flag 

A process can explicitly disable the trapping of an exception by calling 
D1SABLE_EXCEP. Excep_Name is the name of tne exception to be disabled. 
If Queue is true and an exception occurs, tne exception is queued and is 
handled when it is enabled again. If Queue is false, the exception is ignored. 
When an exception handler is entered, the state of the exception in question 
is automatically set to queued. 

If an exception handler is associated through OPEN_EVENT_CHN with an 
event channel and DIS/\BLE_EXCEP is called for that exception, then: 

• If Queue is false, and if an event is sent to the event channel by 
SEND_EVENT_CHN, the SEND_EVENT_CHN call succeeds, but it is 
equivalent to not calling SEND_EVENT_CHN at all. 

• If Queue Is true, and if an event is sent to the event channel by 
SEND EVENT CHN, the SEND_EVENT_CHN call succeeds and a call to 
WAIT"EVENTJDHN receives the event, thus dequeuing the exception. 
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5.7.3 ENABLE_EXCEP Exception Management System Call 

ENABLE_EXCEP (Var Errftuni: Integer; 

Var Excep-narae:t_ex_name) 

ErrNuni: Error indicator 

Excep_Name: Name of exception to be enabled 

ENABLEJEXCEP causes an exception to be bandied again. Since the 
Operating System automatically disables an exception when its exception 
handler is entered (see DIS/\BLE_EXCEP), tne exception handler should 
explicitly re-enable the exception before it returns to the process. 
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5.7.4 INFO.excep Exception Management system Call 

INFOJEXCEP (Var ErrNum:lnteger; 

Var Excepjtame:t_ex_nane; 
Var Excep_status:t_ex_sts) 

ErrNum: Error indicator 
Excep_Name: Name of exception 
Excep_Status: status of exception 

INFO_EXCEP returns information aoout the exception specified by 
Excep_Name. The parameter Excep_Status is a record containing information 
about the exception. This record contains: 

t_ex_sts - RECORD (» exception status *) 

Ex_occurred_f .-Boolean; ("exception occurred flag *) 
Ex_state:t_ex_state; (» exception status *) 

Nun excep .* integer; (*no. of exceptions queued *) 
Hdl_adr:Longadr; ("exception handler's address •) 
END; 

Once Ex_occurred_f has been set to true, only a call to FLUSH_EXCEP can 
set it to false. 
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5.75 SIGNAL_EXCEP Exception Management system Call 

SIGNAL_EXCEP (Var ErrNum: Integer; 

Var Excep_Na«e:t_ex_na«e; 
Var Excep_Data: tjex_data) 

ErrNum: Error indicator 

Excep_name: Name of exception to be signaled 

Excep_Data: Information for exception handler 

A process can signal the occurrence of an exception by calling 
SIGNAL_EXCEP. The exception handler associated with ExcepJMame is 
entered. It is passed ExcepJData, a data area containing information about 
the nature and cause of the exception. The structure of this information area 
is: 

array [0..size_exdata] of Longlnt 

SIGNALJEXCEP can be used for user-defined exceptions and for testing 
exception handlers defined to handle system-defined exceptions. 
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5.7.6 flushjexcep Exception Management system call 

FLUSH.EXCEP (Var ErrNumlnteger; 

Var Excep_Nane:t_ex_name) 

ErrNum: Error inOicator 

Excepjlame: Name of exception whose queue is flushed 

FLUSHJEXCEP clears out the queue associated with the exception 
Excep_Name and resets its "exception occurred" flag. 
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5.8 Event Management System Calls 

This section describes all the Operating System calls that pertain to event 
management. A summary of all the operating System calls can be found in 
Appendix A. The following special types are used in event management calls: 

Pathname = STRINS[255]; 
T_ex_name = STRING [16]; 
T_chn_sts = Record 

chn_type : chnjcind; 
num_events : integer; 
openjrecv : integer; 
open_send : integer; 
ec_name : pathnames- 
end; 
chn_kind = (wait_ec, call_ec); 
T_waitlist = Record 

length: integer; 

refnum:array [0..10] of integers- 
end; 
P_r_eventblk = A r_eventblk; 
R_eventblk = Record 

event_header : t_eheader; 
event_text : t_event_text; 
end; 
T_eheader = Record 

send_pid : longint; 
event_type : longint; 
end; 
T_event_text = array [0..9] of longint; 
P_s_eventblk = A s_eventblk; 
S_eventblk = T_event_text; 
Timestmp_interval = Record 

sec -.longint; 
msec:0. .999; 
end; 
Time_rec = Record 

year -.integers- 
day :1.. 366; 
hour : -23.. 23; 
minute : -59.. 59; 
second:0..59; 
msec: 0.. 999; 
end; 



5-17 



Operating System Reference Manual Exceptions and Events 

5.8.1 MAKE_EVENTjCHN Event Management system call 

MAKE_EVENT_CHN (Var ErrNum: Integer; 

Vax Event jDhnJiaraezPathname) 

ErrNum: Error indicator 

Event_Chn_Name: Pathname of event channel 

MAKE_EVENT_CHN creates an event channel with the name given in 
Event_Chn_Name. The name must he a File System pathname; it cannot be 
null. 
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5.8.2 KILL_EVENT_CHN Event Management system Call 

KILL_EVENT_CHN (Var ErrNum: Integer; 

Var Event_Chn_Name:Pathname) 

ErrNum: Error indicator 

Event_Chn_Name: Pathname of event channel 

To delete an event channel, call KILL_EVENT_CHN. The actual deletion is 
delayed until all processes using the event channel have closed it. In the 
period between the KILL_EVENT_CHN call and the channel's actual deletion, 
no processes can open it. A channel can be deleted by any process that 
knows the channel's name. 
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5.8.3 OPEN_EVENT_CHN Event Management System Call 

OPEN_EVENT_CHN (Var ErrNum: Integer; 

Var E vent_Chn_Name : Pathname; 
Var Ref num : Integer; 

ExcepName : t_ex_name; 

Receiver : Boolean) 

ErrNum: Error indicator 

Event _Chn_Name : Pathname of event channel 
RefNum: Identifier of event channel 

ExcepJMame: Exception name, if any 

Receiver: Access mode of calling process 

CPEN_EVENT_CHN opens an event channel and defines its attributes from trie 
process point of view. RefNum is returned by the Operating System to be 
used in any further references to the channel. 

Event_Chn_Name determines whether the event channel is locally or globally 
defined. If it is a null string, the event channel is locally defined. If 
Event_Chn_Name is not null, it is the File System pathname of the channel. 

ExcepName determines whether the channel is an event-wait or event-call 
channel. If it is a null string, the channel is of event-wait type. Otherwise, 
the channel is an event-calf channel and Excep_Name is the name of the 
exception that is signaled when an event arrives in the channel. Excep_Name 
must be declared before its use in the OPEN_EVENT_CHN call. 

Receiver Is a Boolean value indicating whether the process is opening the 
channel as a sender (Receiver is false) or a receiver (Receiver is true). A 
local channel (one with a null pathname) can be opened only to receive 
events. Also, a call- type channel can only be opened as a receiver. 
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5.8.4 close_event_chn Event Management system call 

CLOSE_EVENT_CHN (Var ErrNum : integer; 
RefNum: Integer) 

ErrNum: Error indicator 

RefNum: Identifier of event channel to be closed 

CLOSE_EVENT_CHN closes the event channel associated with RefNum. Any 
events queued in the channel remain there. The channel cannot he accessed 
until it is opened again. 

If the channel has previously been killed with KILL_EVENT_CHN y you cannot 
open it after it has been closed. 

If the channel has not been killed, it can be opened by OPEN_EVENT_CHN. 
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5.8.5 INF0_EVENT_CHN Event Management system Call 

INFO_EVENT_CHN (Var ErrNum: Integer; 
RefNum: Integer; 
Var Chn_Info:t_chn_sts) 

ErrNum: Error indicator 

RefNum: Identifier of event channel 

Chn_Info: Status of event channel 

1NF0_EVENT_CHN gives a process information about an event channel. The 
Operating System returns a record, Chn_Info> with information pertaining to 
the channel associated with RefNum. 

The definition of the type of the Chnjnfo record is: 

t_chn_sts = 

RECORD (* event enamel status *) 

Chn_type:Chn_kind; (* waitjec or calljec *) 
Num_events: Integer; (* number of queued events ») 
Open_recv: Integer; (* number of processes reading enamel *) 
Open_send: integer; (* no. of processes sending to this 

enamel ») 
Ec_name: pathname; (* event enamel name ») 
END; 
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5.8.6 WAIT_EVENT_CHN Event Management system Call 

«AITJEVENT_CHN (var ErrNum: Integer; 

Var •ait_List:t_waitlist; 
Var Ref Num : Integer; 

Event_Ptr : p_r_eventblk ) 

ErrNum: Error indicator 

Wait_List: Record with array of event channel refnums 

Ref Num: Identifier of channel that had an event 

Event_Ptr: Pointer to event data 

WAITJEVENTjCHN puts the calling process In a waiting state pending the 
arrival of an event in one of the specified channels. WaitJJst is a pointer to 
a list of event channel identifiers. When an event arrives in any of these 
channels, the process is made ready to execute. RefNum identifies which 
channel got the event and Event_Ptr points to the event itself. 

A process can wait for any Boolean combination of events. If it must wait 
for any event from a set of channels (an OR condition), it should call 
WAIT_EVENT_CHN with WaitJList containing the list of event channel 
identifiers. It on the other hand, it must wait for all the events from a set 
of channels (an AND condition), then for each channel in the set, 
WAIT_EVENT_CHN should De called with WaitJJst containing just that 
channel identifier. 

The structure of t_waitlist is: 

RECORD 
Length : Integer; 
Ref num: Array [Q.. size jraitlist] of Integer; 

END; 

Event_Ptr is a pointer to a record containing the event header and the event 
text. Its definition is: 

Pjr_eventblk = A r_eventblk; 
R_eventolk = Record 

event_header : t_eneader; 

event_text : t_event_text; 
end; 
T_eneader = Record 

send _pid : longint; 

event_type : longint; 
end; 
T_event_text = array [0. .9] of longint; 

Send_pid is the process id of the sender. 
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Currently, the possible event type values are: 

1 - Event sent by user process 

2 - Event sent by system 

When you receive the SYS_SON_TERM event the first longint of the event 
text contains the termination cause of the son process. The cause is same as 
that given in the SYS_TERM1NATE exception given to the son process. The 
rest of the event text can be filled by the son process. 

If you call WAIT_EVENT_CHN on an event-call channel that has queued 
events, the event is treated just like an event in an event-wait channel. If 
WAIT_EVENT_CHN is called on an event-call channel that does not have any 
queued events, an error is returned. 
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5.8.7 FLUSH_EVENT_CHN Event Management System call 

FLUSH_EVENT_CHN (Var ErrNum : Integer; 
RefNumrlnteger) 

ErrNum: Error indicator 

RefNum-. Identifier of event channel to be flushed 

FLUSH_EVENT_CHN clears out the specified event channel. All events 
queued in the channel are removed. If FLUSH_EVENT_CHN is called by a 
sender, it has no effect. 
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5.8.8 SENO_EVENT_CHN Event Management system Call 

SO»_EVENT_CHN (Var ErrNum: Integer; 
Ref Num.- Integer; 
Event_Ptr :p_s_eventblk; 
Interval : Timestrap_interval; 
Clktirae : Time_rec) 

ErrNum: Error indicator 

RefNum: Channel for event 

Event_Ptr: Pointer to event data 

Interval: Timer for event 

Clktime: Time data for event 

SEND_EVENT_CHN sends an event to the channel specified by RefNum. 
Event_Ptr points to the event that is to be sent. The event data area 
contains only the event text; the header is added by the system. 

If the event is of the event-wait type, the event is queued. Otherwise the 
Operating System signals the corresponding exception for the process receiving 
the event. 

If the channel is opened by several senders, the receiver can sort the events 
by the process identifier, which the Operating System places in the event 
header. Alternatively, the senders can place predefined identifiers, which 
identify the sender, in the event text. 

The Interval parameter indicates whether the event is a timed event. 

NOTE 

Timed events will not be supported in future releases of the operating 
System. The interval and Clktime parameters will be ignored in future 
releases. If you want your software to be upward-compatible, always 
set both fields of the Interval parameter to zero. 



Timestmpjnterval is a record containing a second and a millisecond field. If 
both fields are 0, the event is sent immediately. If the second given is less 
than 0, the millisecond field is ignored and the Timejrec record is used. If 
the time in the Timejrec has already passed, the event is sent immediately. 
If the millisecond field is greater than 0, and the second field is greater than 
or equal to 0, the event is sent that number of seconds and milliseconds from 
the present 

A process can time out a request to another process by sending Itself a timed 
event and then waiting for the arrival of either the timed event or an event 
indicating the request has been served. If the timed event is received first, 
the request has timed out A process can also time its own progress by 
periodically sending Itself a timed event through an event-call event channel. 
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5.9 Clock System calls 

This section describes all the Operating System calls that pertain to the clock. 
A summary of all the Operating System calls can be found in Appendix A 

The following special types are used in clock calls: 

Timestmp_interval = Record 

sec:longint; 
msec : 0. .999; 
end; 
Timejrec = Record 

year : integers- 
day:!.. 366; 
hour : -23.. 23; 
minute : -59.. 59; 
second :0.. 59; 
msec:0. .999; 
end; 
Hourjrange = -23. .23 
Minutejrange = -59.. 59; 



5-27 



Operating System Reference Manual Exceptions and Events 

5.9.1 delayjtime Clock system call 

DELAYJIME (Var ErrNun: Integer; 

Interval :Timestmp_interval; 
Clktime :Time_rec) 

ErrNum: Error indicator 
Interval: Delay timer 
Clktime: Tine information 

D€LAY_T1ME stops execution of the calling process for the number of seconds 
and milliseconds specified in the Interval record. If this time period is zero, 
DELAYJT1ME has no effect If the period is less than zero, execution of the 
process is delayed until the time specified by Clktime. 
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5.9.2 GETJIME Clock System Call 

GETJTME (Var ErrNum: Integer; 

Var SysJTime :Time_rec) 

ErrNum: Error indicator 
Sysjlme: Time information 

GET_TIME returns tne current system clock time in the record SysJTime. The 
msec field of SysJTime always contains a zero on return. 
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5.9.3 set_local_time_diff Clock System call 

SETJ_OCAL_TIME_DIFF (Var ErrNum: Integer; 

Hour :Hour_range; 
Minute : Minute_range) 

ErrNum: Error indicator 

Hour: Number of hours difference from the system clock 

Minute: Number of minutes difference from the system clock 

SET_LOCAL_TIME_DIFF informs the Operating System of the difference in 
hours and minutes between the local time and the system clock. Hour and 
Minute can be negative. 
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5.9.4 CONVERT_TIME Clock System call 

CONVERTJTME (Var ErrNum: Integer; 

Var Sys_Time:Tirae_rec; 
Var Local_Time:Time_rec; 
To_Sys:Boolean) 

ErrNum: Error indicator 

Sysjlme: System clock time 

Local_Time: Local time 

To_Sys: Direction of time conversion 

CONVERT_TIME converts between local time and system clock time. 

To_Sys is a Boolean value indicating in wnicn direction the conversion is to 
go. If TojSys is true, the system takes the time data in Local_Time and puts 
the corresponding system time in Sys_Time. If TojSys is false, the system 
takes the time data in Sysjrime and puts the corresponding local time in 
Local_TIme. Both time data areas contain the year, month, day, hour, minute, 
second, and millisecond. 
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Configuration 



Every Lisa system is configured using the Preferences tool. Preferences 
places the configuration state of the system in a special part of the system's 
memory called parameter memory Although parameter memory is not 
contained on a disk, it is supplied with battery power so that the contents are 
kept even when the system is turned off. The batteries are charged as long 
as the Lisa is plugged in, even if the unit is powered off. If line power is 
lost, the batteries will keep parameter memory secured for several hours, in 
addition, every time parameter memory is changed, a copy of the new data is 
made on the boot disk. If the contents of parameter memory are lost, this 
disk copy is automatically restored to parameter memory. 

Since the devices actually connected may differ from the configuration stored 
in parameter memory, three calls are provided that allow programs to request 
information about the configuration of the system. 

NOTE 

Configuration System Calls will be changed in future releases of the 
Operating System. Do not use these calls if you want your software to 
be upward-compatible. 



6.1 Configuration System Calls 

This section describes all the Operating System calls that pertain to 
configuration. A summary of all the Operating System calls can be found in 
Appendix A. Special data types used by configuration calls are defined along 
with the calls. 
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6.1.1 CARDSJEQUPPED configuration system call 

CARDS.EQUIPPED (Var ErrNun: Integer; 

Var In_Slot:Slot_array) 

ErrNum: Error code 

In_Slot: Identifies the types of cards configured 

This call returns an array snowing the types of cards which are In the various 
card slots. 

The definition of Slotarray Is: 

slot_array = array [1..3] of card_types; 

where: 

card_types » (rocard, 

apple_cant 
n_port_carct 
netjcard, 
laserjcard); 
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6.1.2 GETjDGNFIQJMAME Configuration System Call 

GET_CONFIG_NAHE (Var Ermum: Integer; 
Devpostn :Tports; 
Var Devnane:E_Nane) 

Errnum: Error code 

Devpostn: A port identifier 

Devname: The name of the device attached to the port 

This call returns the name of the device configured at the port given in 
Devpostn See OSBOQTVOL for the definition of Tports. Type EJMame is 
defined as: 

E_Name = STRING [32]; 
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6.13 osbootvol Configuration system call 

0SB0OTV0L (Var ErrNum-.Integer) : Tports 

ErrNum: Error code 

Tports: Identifies the port to which the boot volume is attached 

OSBOOTVOL is a function that returns the identifier for the port attached to 
the boot volume. This port might not be the port configured for the boot 
volume, since it is possible for the user to override the default boot. Note 
that the port identifier is not the same as the device name. You can use 
GET_CONFIG_NAME to find out the name of the device attached to the port. 

Tports is a set that has this definition: 

Tports = (uppertvlg, lovertvig, parallel, 
slotll, slotl2, slotl3, slotl4> 
SlOt21, SlOt22, SlOt23, Sl0t24, 
SlOt3i, Sl0t32, SlOt33, SlOt34> 
seriala, serialb, mainjconsole, altjconsole, 
tjnouse, t_speaker, tjextral, t_extra2, t_extra3); 
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Appendix A 
Operating System Interface Unit 



UNIT syscall; 
INTRINSIC; 

INTERFACE 

CONST 

maxjename = 32; 
raaxjpathname = 255; 
max_label_size = 128; 
lenexname = 16; 
size exdata = 11; 



(* system call definitions unit *) 



(* maximum length of a file system object name 
(* maximum length of a file system pathname 
(* maximum size of a file label, in bytes 
(* length of exception name 
(* 48 bytes, exception data block should have the 
same size as r eventblk, received event block 



sizejetext = 9; 
size waitlist = 10; 



(* event text size - 40 bytes * 

(* size of wait list - should be same as reqptr_list * 



(* exception kind 
call_term = 0; 
ended = 1; 
self Jellied = 2; 
killed = 3; 
fthTjteni = 4; 
bad syscall = 5; 
baderrnum = 6; 
swapjerror = 7; 
stk_overf low = 8; 
data_overf low = 9; 
parity_err = 10; 



definitions for , SYS_TERh^NATE , exception 

* process called terminate_process 

* process executed 'end' statement 

* process called killjnrocess on self 

* process was killed by another process 

* process's father is terminating 

* process made invalid sys call - subcode bad 

* process passed bad address for errnum parm 

* process aborted due to code swap-in error 

* process exceeded max size (+T rmn) of stack 

* process tried to exceed max data space size 

* process got a parity error while executing 



defjdivzero = 11; (* default handler for div zero exception was called 

def_value_oob = 12; (* " for value oob exception 

defjDvf w = 13; (* " for overflow exception 

def_nmi_key = 14; (» " for Mil key exception 

defjrange = 15; (» " for 'SYSJ/ALUEJDOB' excep due to value range err 

def_str_index = 16; (* " for "SYS_VALUEJOOB' excep due to string index err »' 
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bus_error = 21; 
addrjerror = 22; 
illg_inst = 23; 
privj/iolation = 24; 
ltae_1010 = 26; 
llne_llll = 27; 

unexpectedex - 29; 



C 

C 

(* 



bus error occurred 
address error occurred 
Illegal Instruction trap occurred 
privilege violation trap occurred 
line 1010 emulator occurred 
line 1111 emulator occurred 



div_zero 

value_oob 

ovfw 

nmi_key 

valuejrange 

str index 



31; 
32; 
33; 
34; 
35; 
36; 



(* an unexpected exception occurred 
exception kind definitions for hardware exception 



excep kind for value range and string index error 
Note that these two cause 'SYSJYALUEJOOB' excep 



(*device_control functions*) 



aVParity = l; 

dvOutOTR = 2; 
dvOutXON = 3; 
dvOutOelay = 4; 
dvBaud = 5; 
dvlnVait = 6; 
dVlnDTR = 7; 
dvInXON = 8; 
dvTypeahd = 9; 
dvDiscon = 10; 
dvOutNoHS = 11; 
dvErrStat = 15; 
dvQetEvent = 16; 
dvAutoLF - 17; 
dvOiskStat = 20; 
dvDiskSpare = 21; 

TYPE 

pathname = string [max_pathname]; 
e_name » string [maxjename]; 
namestring = string [20); 



*) 
*) 
*) 
*> 
*> 
•> 



*> 



(*RS-232*) 

(•RS-232*) 

(*RS-232») 

("RS-232*) 

(*RS-232*) 

(*RS-232, CONSOLE*) 

(*RS-232*) 

(*RS-232*) 

(*RS-232*) 

(*RS-232*) 

(*RS-232*) 

(*PR0FILE*) 

(*C0NS0LE*) 

(•RS-232, CONSOLE, PARALLEL PRINTER*) (*not yet*) 

("DISKETTE, PROFILE*) 

("DISKETTE, PROFILE*) 



procinf oRec ■ 


record 


progpathname : 


pathname; 


global id 


: longint; 


fatherjd 


: longint; 


priority 


: 1..255; 


state 


: (pactive. 


data in 


: boolean 


end- 





psuspended, pvaiting); 
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Tdstype = (ds_sharat ds_private); (* types of data segments *)' 

dsirrfoRec = record 

mem_size : longint; 

disc_size: longint; 

numb_open : integer; 

ldsn : integer; 

boundF : boolean; 

presentF : boolean; 

creatorF : boolean; 

rwaccess : boolean: 

segptr : longint; 

volname: e_name; 
end; 



t_ex_name = string [len_exname]; 

longadr = "longint; 

t_ex_state = (enabled, queued, ignored); 

P_ex_data = "t_ex_data; 

t_ex_data = array [0..size_exdata] of longint; 

t_ex_sts = record 

ex_occurred_f : boolean; 

ex_state : t_ex_state; 

num_excep : integ^r; 

ndl_adr : longadr; 

end; 

p_env_blk 

env_blk = 

pc 

sr 

dd 

dl 

d2 

d3 

d4 

d5 

d6 

d7 

ao 

al 

a2 

a3 

a4 



as 
a6 
a7 



end; 



= "env_blk; 

record 

longint; 

integer; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 



(* exception name *) 

(* exception state •) 

(* exception data blk «) 

(* exception status *) 

(* exception occurred flag *) 

(* exception state *) 

(* number of exceptions q'ed *) 

(* handler address *) 



environment block to pass to handler *) 
program counter *) 

status register *) 

data registers 0-7 «) 



(* address registers 0-7 
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(* terminate exception data block 



p_term_ex_data = *term_ex_data; 
term_ex_data = record 

case excep_kind : longint of 

call_term, 

ended, 

selfjcilled, 

killed, 

fthr_term 

bad_syscall, 

Dad_errnunt 

swap_error, 

stk_overflow, 

data_pverflo», 

parity_err : (); (* due to process termination 



illg_inst, 
priv_violation, 

line_1010, 

line_llll, 

def_div_zero y 

def_value_oob, 

def_ovfw, 

def_nmi_key 



(* due to illegal instruction, privilege 

violation *) 

(* due to line 1010, nil emulator *) 



end; 



(* terminate due to default handler for hardware 
exception *) 

: (sr : integer; 

pc : longint); (• at the time of occurrence ») 

defjrange, 

def_str_index (* terminate due to default handler for 

, SYS_VALUE_pOB" excep for value range or string 
index error *) 

: (value_check : integer; 
upper_bound : integer; 
lower_bound : integers- 
return _pc : longint; 
caller_a6 : longint); 
bus_error, 

addr_error (» due to bus error or address error *) 
: (fun_field : packed record (« one integer •) 

filler : 0. .$7ff; (* 11 bits «) 

r_«_flag : boolean; 
i_n_f lag : boolean; 
fun code : 0..7; (• 3 bits *) 
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access_adr : longint; 
instjregister : integer; 
sr_error : Integer; 
pc_error : longint); 
end; 

p_hard_ex_data = ~hard_ex_data; 

hard_ex_data = record 

case excep_kind : longint of 
div_zero, value_oob, ovfw 
: (sr : integer; 
pc : longint); 
valuejrange, str_index 
: (value_check : integer; 
upper_bound : integer; 
3ower_bound : integers- 
return _pc : longint; 
caller_a6 : longint); 

end; 



(* hardware exception data block 



accesses - (dread, dwrite, append, private, globaljrefnum); 

mset = set of accesses; 

iomode = (absolute, relative, sequential); 

UID = record (^unique id«) 

a,b: longint 
end; 



timestmp_interval = record 

sec : longint; 

msec : 0..999; 
end; 



(* time interval *) 

(* number of seconds *) 

(* number of milliseconds within a second *) 



info_type = (device_t, volume_t, object_t),* 

devtype = (diskdev, pascalbd, seqdev, bitbkt, non_io); 

filetype = (undefined, MDDFfile, rootcat, freelist, badblocks, sysdata, 

spool, exec, usercat, pipe, bootf ile, swapdata, swapcode, ramap, 

userfile, killedobject); 

entrytype= (emptyentry, catentry, linkentry, fileentry, pipeentry, ecentry, 
killedentry); 
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f s_lnfo = record 
name : e_name; 
dlr_path : pathname; 
machine_id : longint; 
fsjovemead : integer; 
result_scavenge : integer- 
case otype : inf o_type of 
device_t, volume_t: ( 
iochannel : integer; 
devt : devtype; 
slot_no : integer; 
f s_size : longint; 
vol_slze : longint; 
blockstructured, mounted : boolean; 
opencount : longint; 

privatedev, remote, lockeddev : boolean; 
mount_pending, unmount_pendlng : boolean; 
volname, password : e_name; 
f sversion, volnum : integer; 
volid : UID; 
backup_voiid : UID; 

blocksize, datasize, clustersize, filecount : integer; 
label_size : integer; 
f reecount : longint; 
D7VC, DTCC, DTVB, OTVS : longint; 
master_copy_id, copy_thread : longint; 
overraount_stamp : UID; 
boot_code : integer; 
bootjenviron : integer; 
privileged, write_protected : boolean; 
master, copy, copy_f lag, scavenge_flag : boolean; 
vol_left_mounted : boolean ); 

object_t : ( 

size : longint; 

psize : longint; (• physical file size in bytes •) 

lpslze : integer; (* logical page size in bytes for this file *) 

ftype : filetype; 

etype : entrytype; 

DTD, DTA, DTft DTB, DTS : longint; 

ref nun : integer; 

fmark : longint; 

acmode : mset; 

nreaders, nwriters, nusers : integer; 

fuid : UID; 

user_type : integer; 

user_subtype : integer; 
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systemtype : integer; 
eof, safetyjon, kswitch : boolean; 
private, locked, protected, inaster_file : boolean; 
file_scavenged, file_closed_by_OS, file_left_open: boolean) 
end; 

dctype = record 

dcversion : Integers- 
decode : integer; 
dedata : array [0..9] of longint; 

end; 



t_waitlist = record 

length : integer; 

refnum : array [0..size_waltlist] of integers- 
end; 



(* user/driver defined data 
(* wait list 



tjBheader - record 
send_pid : longint; 
event_type : longint; 

end; 



(* event header «) 

(* sender's process id *) 
(* type of event *) 



t_event_text = array [0..size_etext] of longint; 
p_r_eventblk = A r_eventblk; 
r_eventblk = record 

event_header : tjeheader; 

event_text : t_event_text; 
end; 

p_s_eventblk = *s_eventblk; 
s_eventblk = t_event_text; 



time_rec = record 
year : integers- 
day : 1..366; 
hour : -23.. 23; 
minute : -59. .59; 
second : 0..59; 
msec : 0..999; 

end; 



(» Julian date *) 
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chnjcind = (valtjec, calljec); 
t_chn_sts ■ record 

chntype : chnjdnd; 

num_events : Integer; 

openjrecv : integer; 

open_send : integer; 

ec_name : pathname; 
end; 

hourjrange = -23. .23; 
mlnute_range - -59.. 59; 



(* channel status •) 

(« channel type 

(* number of events queued * 

(* number of opens for receiving * 

C* number of opens for sending •' 

(» event channel name * 



{configuration stuff: } 

tports = (uppertvig, lowertvig, parallel, 

SlOtll, SlOtl2, SlOtl3, SlOttt, 

SlOt21, SlOt22, SlOt23, SlOt24, 

SlOt3L SlOt32, SlOt33. Sl0t34, 

seriala, serialb, mainjoonsole, altjconsole, 

tjnouse, t_speaker, tjextral, t_extra2, t_extra3); 

card_types = (nojcard, applejcard njportjcard, netjcarcL laserjcard); 

slotjarray = array [1..3] of card_types; 

{ Lisa Office System parameter memory type } 

pmByteunique = -128.. 127; 

pMemRec = array[l..62] of pmByteUnique; 

(* File System calls *) 

procedure MAKEFILE (var ecode: integer; var path: pathname; 

label.size : integers- 
procedure make_pipe (var ecode: integer; var path:pathname; 

label_size : Integer ); 

procedure MAKE_CATALOG (var ecode: integer; var path -.pathname; 
label_slze : integer); 

procedure MAKEJLINK (var ecode: Integer; var path, ref :pathname; 
label_size : integer); 



A-8 



Operating System Reference Manual Operating System interface .unit 

procedure KILL_0BJECT (var ecode: Integer; var path: pathname); 

procedure UNKILL_FILE (var ecode: integer; refnum: Integer; var 
new_name : ename); 

procedure OPEN (var ecode: integer; var path: pathname; var refnum : integer; 
manip:mset); 

procedure CL0SE_0BJECT (var ecode .-integer; refnum: integer); 

procedure READJDATA (var ecode: Integer; refnum: Integer; data_addr:longint; 
count :longint; var actual -.longint; mode-.iomode; 
offset :longint); 

procedure WRITEJDATA (var ecod&integer; refnuntinteger; data_addr:longlnt; 
count:longint; var actual:longint; mode:iomode; 
offset:longint); 

procedure FLUSH (var ecode: integer; refnum: integer ); 

procedure LOOKUP (var ecocfeinteger; var patrtpathname; var 
attriDutes:fs_info); 

procedure INFO (var ecode: integer; refnum: integer; var refinfo:fs_info); 

procedure ALLOCATE (var ecode:integer; refnuntinteger; axitiguous:boolean; 
count:longint; var actual:longint); 



procedure TRUNCATE (var ecoofeinteger; refnuntinteger); 

procedure COMPACT (var ecocle:integer; refnuntinteger); 

procedure RENAME_ENTRY ( var ecode: integer; var path .-pathname; var 
newname:e_name ); 

procedure READ_LABEL ( var ecode-.integer; var path:pathname; 

data_addr:longint; count:longint; var actual:longint ); 

procedure WRITE_LABEL ( var ecoofeinteger; var path:pathname; 

data_addr:longint; countrlongint; var actuaL-longint ); 

procedure MOUNT ( var ecode: integer; var vname : ename; var password : 
e_name ;var devname : e_name); 

procedure UNMOUNT ( var ecode: integer; var vname : e_name ); 
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procedure SET_lfORKING_DIR ( var ecode: integer; var path: pathname ); 

procedure GETJIORKINGJHR ( var ecode: integer; var path: pathname ); 

procedure SETSAFETY (var ecode: integer; var path: pathname; onoff: boolean ); 

procedure DEVICE_CONTROL ( var ecode: integer; var path: pathname; 
var cparm : dctype ); 

procedure RESET_CATALOG (var ecocleiinteger; var path:pathname); 

procedure GET_NEXT_ENTRY (var ecoderinteger; var prefix, entry:e_name); 

procedure SET_FILE_INFO (var ecode rinteger; refnuntinteger; fsi:fs_info); 

(* Process Management system calls *) 

function My_ID:longint; 

procedure Info_Process (var errnuntlnteger; proc_id:longint; var 
proc_info:procinfoRec); 

procedure Yield_CPU (var errnuntinteger; to_any:boolean); 

procedure SetPriority_Process (var errnuntinteger; proc_id-.longint; 
new_priority:integer); 

procedure Suspend_Process (var errnuntinteger; proc_ichlongint; 
susp_family:Doolean); 

procedure Activate_Process (var errnuntinteger; proc_icklongint; 
act_family:hoolean); 

procedure Kill_Process (var errnuntinteger; proc_id:longlnt); 

procedure Terminate_Process (var errnuntinteger; event_ptr:p_s_eventblk); 

procedure hake_Process (var errnuntinteger; var proc_icfclongint; var 
progf ile:pathname; var entryname:namestring; 
evnt_chn_refnuntinteger); 
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(* Memory Management system calls *) 

procedure make_dataseg(var errnum: integer; var segname: pathname; mem_size, 
disc_size: longint; var refnum: integer; var seoptr: 
longint; ldsn: integer; dstype: Tdstype), 4 

procedure kill_dataseg (var errnuntinteger; var segname:patnname); 

procedure open_dataseg (var errnuntinteger; var segnameipatmame; var 
refnuntinteger; var segptnlongint; ldsrninteger); 

procedure close_dataseg (var errnuntinteger; refnuntinteger); 

procedure size_dataseg (var errnuntinteger; refnuntinteger; 

deltamemsizerlongint; var newmemsize:longint; 
deltadlscsize: longint; var newdiscsize: longint); 

procedure info_dataseg (var errnuntinteger; refnuntinteger; var 
dsinfozdsinfoRec); 

procedure setaccess_dataseg (var errnuntinteger; refnuntinteger; 
readonly:Doolean); 

procedure unbind_dataseg (var errnuntinteger; refnuntinteger); 

procedure bind_dataseg(var ermuntinteger; refnuntinteger); 

procedure info_ldsn (var errnuntinteger; ldsn: integer; var refnum: integer); 

procedure f lush_dataseg(var errnum: integer; refnum: integer); 

procedure mem_info(var errnum: integer; var swapspace, dataspace, 
curcodesize, max_codesize: longint); 

procedure info_address(var errnum: integer; address: longint; var refnum: 
integer); 

(* Exception Management system calls ») 

procedure declare_excep_ndl (var errnuntinteger; var excep_name:t_ex_name; 
entry_point:longadr); 

procedure disable_excep (var errnuntinteger; var excep_name:t_ex_name; 
queu&boolean); 
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procedure enable_excep (var errnuntinteger; var excep_name:t_ex_name); 

procedure signal_excep (var errnuntinteger; var excep_name:t_ex_name; 
% excep_data:t_ex_data); 

procedure infoexcep (var errnuntinteger; var excep_name:t_ex_name; var 
excep_status:t_ex_sts); 

procedure flush_excep (var errnuntinteger; var excep_name:t_ex_name); 

(* Event Channel management system calls *) 

procedure make_event_ehn (var errnuntinteger; var event_cnn_name:pathname); 

procedure kill_event_chn (var errnuntinteger; var event_chn_name:pathname); 

procedure open_event_chn (var errnuntinteger; var event_cnn_name:pathname; var 
refnuntinteger; var excep_name:t_ex_name; 
receiver:boolean); 

procedure close_event_chn (var errnuntinteger; refnunt integers- 
procedure info_event_chn (var errnuntinteger; refnuntinteger; var 
chn_infat_chn_sts); 

procedure »ait_event_chn (var errnuntinteger; var wait_list:t_waitlist; var 
refnuntinteger; event_ptr:p_r_eventblk ); 

procedure flush_event_chn (var errnuntinteger; refnuntinteger); 

procedure send_event_chn (var errnuntinteger; refnuntinteger; 

event_ptr:p_s_eventblk; interval:timestmp_interval; 
clktime:time_rec); 



(* Timer functions system calls *) 

procedure delay_time (var errnuntinteger; intervals imestnp_interval; 
clktimertlmejrec); 

procedure get_time (var errnuntinteger; var gmt_time:time_rec); 

procedure set_local_time_diff (var errnuntinteger; hour:hour_range; 
minute:minute_range); 
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procedure convert_time (var ermuntinteger; var gmt_time:time_rec; var 
local_time:time_rec; tojgmt:boolean); 

{configuration stuff} 

function 0SBO0TVOL(var error : integer) : tports; 

procedure GET_CONFIG_NAME( var error: integer; devpostnrtports; var 
devname:e_name); 

procedure CARDS_EQUTPPED(var errorrinteger; var in_slot:slot_array); 

IMPLEMENTATION 

procedure MAKE_FILE; external; 
procedure MAKE_PIPE; external; 
procedure make_catalog; external; 
procedure MAKEJ.INK; externals- 
procedure KILLJJ8JECT; external; 
procedure OPEN; external; 
procedure CLOSEJBJECT; externals- 
procedure READ_DATA; external; 
procedure WRITE_DATA; external; 
procedure FLUSH; externals- 
procedure LOOKUP; externals- 
procedure INFO; externals- 
procedure ALLOCATE; externals- 
procedure TRUNCATE; external; 
procedure COMPACT; external; 
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procedure RENAME_ENTRY; external; 
procedure READJJCEL; external; 
procedure ¥RITE_LABEL; external- 
procedure MOUNT; externals- 
procedure UNMOUNT; external; 
procedure SETJWRKINGDIR; externals- 
procedure GET_«ORKING_DIR; externals- 
procedure SET_SAFETY; externals- 
procedure DEVICE_CONTROL; externals- 
procedure RESET_CATALOG; externals- 
procedure GET_NEXT_ENTRY; externals- 
procedure GET_DEV_NAME; externals- 
function My_ID; externals- 
procedure Info_Process; externals- 
procedure Yield_CPU; external; 
procedure SetPriority_Process; externals- 
procedure Suspend_Process; externals- 
procedure Activate_Process; externals- 
procedure Kill_Process; externals- 
procedure Temdnate_Process; externals- 
procedure Make_Process; external; 
procedure ScnedjDlass; extemal; 
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procedure makejdataseg; external- 
procedure killjdataseg; external; 
procedure openjdataseg,- externals- 
procedure closejdataseg; external; 
procedure slzejdataseg,- externals- 
procedure lnf ojdataseg; externals- 
procedure setaccess_dataseg; externals- 
procedure unblnd_dataseg; external; 
procedure blndjdataseg; externals- 
procedure inf o_ldsn; externals- 
procedure f lushjdataseg; externals- 
procedure roem_inf o; externals- 
procedure declare_excep_hdl; externals- 
procedure disablejexcep; externals- 
procedure enable_excep; externals- 
procedure slgnaljexcep; externals- 
procedure lnf o_excep; externals- 
procedure f lushjexcep; externals- 
procedure make_event_chn; externals- 
procedure kill_event_chn; externals- 
procedure open_event_chn; externals- 
procedure close_event_chn; external; 
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procedure info_event_chn; external; 
procedure *ait_event_chn; external; 
procedure f lush_event_chn; external; 
procedure send_event_chn; external; 

procedure delay_tlme; externals- 
procedure get_tinie; external; 
procedure set_local_time_diff; externals- 
procedure convert_time; externals- 
procedure set_file_lnfo; externals- 
function ENABLEDBG; externals- 
function 0SB007V0L; externals- 
procedure GET_CONFIG_NAME; externals- 
function DISK_LIKELY; externals- 
procedure CARDS_EQUIPPED; external; 
procedure Read_Pt1enu externals- 
procedure irlte_PMem; externals- 
end. 
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SYSJDVERFLOW Overflow exception. Signaled when the TRAPV instruction is 
executed and the overflow condition is on. 

SYS_V/M_UE_ODB Value-out-of-bound exception. Signaled when the CHK 

instruction is executed and the value is less than or greater 
than upper bound. 

SYS_ZERQ_DIV Division by zero exception. Signaled when the D1VS or DIVU 
instruction is executed and the divisor is zero. 

SYSJTERMINATE Termination exception. Signaled when a process is to be 
terminated. 
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SYS_SON_TERM "Son terminate" event type. If a father process has created a son 
process with a local event channel, this event is sent to the 
father process when the son process terminates. 
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-6081 End of exec file input 

-6004 Attempt to reset text file with typed-f ile type 

-6003 Attempt to reset nontext file with text type 

-1885 ProFile not present during driver initialization 

-1882 ProFile not present during driver initialization 

-1176 Data in the object have been altered by Scavenger 

-1175 File or volume was scavenged 

-1174 File was left open or volume was left mounted, and system crashed 

-1173 File was last closed by the OS 

-1146 Only a portion of the space requested was allocated 

-1063 Attempt to mount boot volume from another Lisa or not most recent boot 

volume 
-1060 Attempt to mount a foreign boot disk following a temporary unmount 
-1059 The bad block directory of the diskette is almost full or difficult to read 
-696 Printer out of paper during initialization 
-660 Cable disconnected during ProFile initialization 
-626 Scavenger indicated data are questionable, but may be OK 
-622 Parameter memory and the disk copy were both invalid 
-621 Parameter memory was invalid but the disk copy was valid 
-620 Parameter memory was valid but the disk copy was invalid 
-413 Event channel was scavenged 
-412 Event channel was left open and system crashed 
-321 Data segment open when the system crashed. Data possibly invalid. 
*- 320 Could not determine si ze of data segment 
-150 Process was created, but a library used by program has been scavenged and 

altered 
-149 Process was created, but the specified program file has been scavenged and 

altered 
- 125 Sepcif ied process is already terminating 
- 120 Specified process is already active 
- 1 15 Specified process is already suspended 

100 Specified process does not exist 

101 Specified process is a system process 
110 Invalid priority specified (must be 1..225) 

130 Could not open program file 

131 File System error while trying to read program file 

132 Invalid program file (incorrect format) 

133 Could not get a stack segment for new process 

134 Could not get a syslocal segment for new process 

135 Could not get sysglobal space for new process 

136 Could not set up communication channel for new process 
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138 Error accessing program file while loading 

141 Error accessing a library file while loading program 

142 Cannot run protected file on this machine 

143 Program uses an intrinsic unit not found in the Intrinsic Library 

144 Program uses an intrinsic unit whose name/type does not agree with the 
Intrinsic Library 

145 Program uses a shared segment not found in the intrinsic Library 

146 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

147 No space in syslocal for program file descriptor during process creation 

148 No space in the shared IU data segment for the program's shared IU globals 

190 No space in syslocal for program file description during List_LibFiles 
operation 

191 Could not open program file 

192 Error trying to read program file 

193 Cannot read protected program file 

194 Invalid program file (incorrect format) 

195 Program uses a shared segment not found in the Intrinsic Library 

196 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

198 Disk I/O error trying to read the intrinsic unit directory 

199 Specified library file number does not exist in the Intrinsic Library 

201 No such exception name declared 

202 No space left in the system data area for Declare_Excep_Hdl or 
Signal_Excep 

203 Null name specified as exception name 

302 Invalid LDSN 

303 No data segment bound to the LDSN 

304 Data segment already bound to the LDSN 

306 Data segment too large 

307 input data segment path name is invalid 

308 Data segment already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified 

311 Insufficient system resources 

312 Unexpected File System error 

313 Data segment not found 

314 Invalid address passed to Info_Address 

315 Insufficient memory for operation 

317 Disk error while trying to swap in data segment 

401 Invalid event channel name passed to Make_Event_Chn 

402 No space left in system global data area for Open_Event_Chn 

403 No space left in system local data area for 0pen_Event_Chn 

404 Non-block-structured device specified in pathname 

405 Catalog is full in Make_Event_Chn or open_Event_Chn 

406 No such event channel exists in Kill_Event_Chn 
410 Attempt to open a local event channel to send 
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411 Attempt to open event cnannel to receive when event channel has a receiver 

413 Unexpected File System error in Open_Event_Chn 

416 Cannot get enough disk space for event channel in Open_Event_Chn 

417 Unexpected File System error in Close_Event_Chn 

420 Attempt to wait on a channel that the calling process did not open 

421 Wait_Event_Chn returns empty because sender process could not complete 

422 Attempt to call wait_Event_Chn on an empty event-call channel 

423 Cannot find corresponding event channel after being blocked 

424 Amount of data returned while reading from event channel not of expected 
size 

425 Event channel empty after being unblocked, Wait_Event_Chn 

426 Bad request pointer error returned in Wait_Event_Chn 

427 waltjJst has illegal length specified 

428 Receiver unblocked because last sender closed 

429 Unexpected File System error in wai t_Event_Chn 

430 Attempt to send to a channel which the calling process does not have open 

431 Amount of data transferred while writing to event channel not of expected 
size 

432 Sender unblocked because receiver closed in Send_Event_Chn 

433 Unexpected File System error in Send_Event_Chn 

440 Unexpected File System error in Make_Event_Chn 

441 Event channel already exists in Make_Event_Chn 
445 unexpected File System error in Kill_Event_Chn 
450 Unexpected File System error in Flush_Event_Chn 

530 Size of stack expansion request exceeds limit specified for program 

531 Cannot perform explicit stack expansion due to lack of memory 

532 insufficient disk space for explicit stack expansion 
600 Attempt to perform I/O operation on non I/O request 
602 No more alarms available during driver initialization 

605 Call to nonconf igured device driver 

606 Cannot find sector on floppy diskette (disk unformatted) 

608 Illegal length or disk address for transfer 

609 Call to nonconfigured device driver 

610 No more room in sysglobal for I/O request 

613 Unpermitted direct access to spare track with sparing enabled on floppy 
drive 

614 No disk present in drive 

615 Wrong call version to floppy drive 

616 Unpermitted floppy drive function 

617 Checksum error on floppy diskette 

618 Cannot format, or write protected, or error unclamping floppy diskette 

619 No more room in sysglobal for I/O request 

623 Illegal device control parameters to floppy drive 

625 Scavenger indicated data are bad 

630 The time passed to Delay_Time, Convert_Time / or Send_Event_Chn has 
invalid year 

631 Illegal timeout request parameter 



D-3 



Operating System Reference Manual Error h-lessages 

632 No memory available to initialize clock 

634 Illegal timed event id of - 1 

635 Process got unblocked prematurely due to process termination 

636 Timer request did not complete successfully 

638 Time passed to Delay_Time or Send_Event_cnn more tnan 23 days from 
current time 

639 illegal date passed to Set_Time, or illegal date from system clock in 
Get_Time 

640 RS-232 driver called with wrong version number 

641 RS-232 read or write initiated with illegal parameter 

642 Unimplemented or unsupported RS-232 driver function 

646 No memory available to initialize RS-232 

647 unexpected RS-232 timer interrupt 

648 Unpermitted RS-232 initialization, or disconnect detected 

649 Illegal device control parameters to RS-232 

652 N-port driver not initialized prior to ProFile 

653 No room in sysgiobal to initialize ProFile 

654 Hard error status returned from drive 

655 Wrong call version to ProFile 

656 Unpermitted ProFile function 

657 Illegal device control parameter to ProFile 

658 Premature end of file when reading from driver 

659 Corrupt File System header chain found in driver 

660 Cable disconnected 

662 Parity error while sending command or writing data to ProFile 

663 Checksum error or CRC error or parity error in data read 
666 Timeout 

670 Bad command response from drive 

671 Illegal length specified (must - 1 on input) 

672 Unimplemented console driver function 

673 No memory available to initialize console 

674 Console driver called with wrong version number 

675 Illegal device control 

680 Wrong call version to serial driver 

682 Unpermitted serial driver function 

683 No room in sysgiobal to ir litialize serial driver 

685 Eject not allowed this device 

686 No room in sysgiobal to initialize n-port card driver 

687 Unpermitted n-port card driver function 

688 Wrong call version to n-port card driver 

690 wrong call version to parallel printer 

691 Illegal parallel printer parameters 

692 N-port card not initialized prior to parallel printer 

693 No room in sysgiobal to initialize parallel printer 

694 unimplemented parallel printer function 

695 Illegal device control parameters (parallel printer) 

696 Printer out of paper 
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698 Printer offline 

699 No response from printer 

700 Mismatch between loader version number and Operating System version 
number 

701 OS exhausted its internal space during startup 

702 Cannot make system process 

703 Cannot kill pseudo-outer process 

704 Cannot create driver 

706 Cannot initialize floppy disk driver 

707 Cannot initialize the File System volume 

708 Hard disk mount table unreadable 

709 Cannot map screen data 

710 Too many slot-based devices 

724 The boot tracks do not know the right File System version 

725 Either damaged File System or damaged contents 

726 Boot device read failed 

727 The OS will not fit into the available memory 

728 SYSTEM.OS is missing 

729 SYSTEM.CONFIG is corrupt 

730 SYSTEM.OS is corrupt 

731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

732 SYSTEM.LLD is corrupt 

733 Loader range error 

734 Wrong driver is found. For instance, storing a diskette loader on a ProFile 

735 SYSTEM.LLD is missing 

736 SYSTEM.UNPACK is missing 

737 Unpack Of SYSTEM.OS With SYSTEM.UNPACK failed 

801 IOResult <> on I/O using the Monitor 

802 Asynchronous I/O request not completed successfully 

803 Bad combination of mode parameters 
806 Page specified is out of range 

809 Invalid arguments (page, address, offset, or count) 

810 The requested page could not be read in 

816 Not enough sysglobal space for File System buffers 

819 Bad device number 

820 No space in sysglobal for asynchronous request list 

821 Already initialized 1/0 for this device 

822 Bad device number 

825 Error in parameter values (Allocate) 

826 No more room to allocate pages on device 

828 Error in parameter values (Deallocate) 

829 Partial deallocation only (ran into unallocated region) 
835 Invalid s-file number 

837 Unallocated s-file or I/O error 

838 Map overflow: s-file too large 

839 Attempt to compact file past PEOF 
841 Unallocated s-file or I/O error 
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843 Requested exact fit, Out one could not be provided 

847 Requested transfer count is <- 

848 End of file encountered 

849 Invalid page or offset value in parameter list 
852 Bad unit number 

854 No free slots in s-list directory (too many s-files) 

855 No available disk space for file nints 

856 Device not mounted 

857 Empty, locked, or invalid s-flle 

861 Relative page is beyond PEOF (bad parameter value) 

864 no sysglobal space for volume bitmap 

866 Wrong FS version or not a valid Lisa FS volume 

867 Bad unit number 

868 Bad unit number 

869 Unit already mounted (mountyno unit mounted 
87 No sysglobal space for DCB or MDDF 

871 Parameter not a valid s-file ID 

872 No sysglobal space for s-file control block 

873 Specified file is already open for private access 

874 Device not mounted 

875 invalid s-f lie ID or s-file control block 
879 Attempt to postion past LEOF 

881 Attempt to read empty file 

882 No space on volume for new data page of file 

883 Attempt to read past LEOF 

884 Not first auto-allocation, but file was empty 

885 Could not update filesize nints after a write 

886 No syslocal space for I/O request list 

887 Catalog pointer does not indicate a catalog (bad parameter) 

888 Entry not found in catalog 

890 Entry by that name already exists 

89 1 Catalog is full or is damaged 

892 Illegal name for an entry 

894 Entry not found, or catalog is damaged 

895 Invalid entry name 

896 Safety switch is on— cannot kill entry 

897 Invalid bootdev value 

899 Attempt to allocate a pipe 

900 Invalid page count or FCB pointer argument 

901 Could not satisfy allocation request 

921 Pathname invalid or no such device 

922 Invalid label size 

926 Pathname invalid or no such device 

927 Invalid label size 

941 Pathname invalid or no such device 

944 Object is not a file 

945 File is not in the killed state 
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946 Pathname invalid or no sucn device 

947 Not enough space in syslocal for File System refdb 

948 Entry not found in specified catalog 

949 Private access not allowed if file already open shared 

950 Pipe already in use, requested access not possible or dwrite not allowed 

951 File is already opened in private mode 

952 Badrefnum 

954 Badrefnum 

955 Read access not allowed to specified object 

956 Attempt to position FMARK past LEOF not allowed 

957 Negative request count is illegal 

958 Nonsequential access is not allowed 

959 System resources exhausted 

960 Error writing to pipe while an unsatisfied read was pending 

961 Badrefnum 

962 No WRITE or APPEND access allowed 

963 Attempt to position FMARK too far past LEOF 

964 Append access not allowed in absolute mode 

965 Append access not allowed in relative mode 

966 Internal inconsistency of FMARK and LEOF (warning) 

967 Nonsequential access is not allowed 

968 Badrefnum 

97 1 Pathname invalid or no such device 

972 Entry not found in specified catalog 
974 Badrefnum 

977 Bad refnum 

978 Page count is nonpositive 

979 Not a block-structured device 

981 Bad refnum 

982 No space has been allocated for specified file 

983 Not a block-structured device 

985 Badrefnum 

986 No space has been allocated for specified file 

987 Not a block-structured device 

988 Badrefnum 

989 Caller is not a reader of the pipe 

990 Not a block-structured device 

994 Invalid refnum 

995 Not a block-structured device 

999 Asynchronous read was unblocked before it was satisfied 

1021 Pathname invalid or no such entry 

1022 No such entry found 

1023 Invalid newname, check for '-' in string 

1024 New name already exists in catalog 

103 1 Pathname invalid or no such entry 

1032 Invalid transfer count 

1033 No such entry found 
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1041 Pathname Invalid or no such entry 

1042 Invalid transfer count 

1043 No such entry found 

1 051 No device or volume by that name 

1052 A volume is already mounted on device 

1053 Attempt to mount temporarily unmounted boot volume just unmounted from 
this Lisa 

1054 The bad block directory of the diskette is invalid 

1061 No device or volume by that name 

1 062 No volume is mounted on device 

1071 Not a valid or mounted volume for working directory 

1091 Pathname invalid or no such entry 

1092 No such entry found 
1101 Invalid device name 

1121 Invalid device, not mounted, or catalog is damaged 

1128 Invalid pathname, device, or volume not mounted 

1130 File is protected; cannot open due to protection violation 

1131 No device or volume by that name 

1 1 32 No volume is mounted on that device 

1133 No more open files in the file list of that device 

1134 Cannot find space in sysglobal for open file list 

1 135 Cannot find the open file, entry to modify 

1 1 36 Boot volume not mounted 

1 137 Boot volume already unmounted 

1138 Caller cannot have higher priority than system processes when calling ubd 

1141 Boot volume was not unmounted when calling rbd 

1 142 Some other volume still mounted on the boot device when calling rbd 

1 143 No sysglobal space for MDDF to do rbd 

1144 Attempt to remount volume which is not the temporarily unmounted boot 
volume 

1145 No sysglobal space for bit map to do rbd 

1158 Track -by- track copy buffer is too small 

1159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by-track copy 

1161 Invalid final shutdown mode 

1162 Power is already off 

1163 Illegal command 

1 164 Device is not a diskette device 

1165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1167 Not a block -structured device 

1168 Device name is invalid 

1169 Could not access device before initialization using default device 
parameters 

1170 Could not mount volume after initialization 

1171 '-' is not allowed in a volume name 

1172 No space available to initialize a bitmap for the volume 
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1176 Cannot read from a pipe more than half of its allocated physical size 

1177 Cannot cancel a read request for a pipe 

1178 Process waiting for pipe data got unDlocked because last pipe writer closed 
it 

1180 Cannot write to a pipe more than half of its allocated physical size 

1 181 No system space left for request block for pipe 

1182 Writer process to a pipe got unblocked before the request was satisfied 

1 183 Cannot cancel a write request for a pipe 

1184 Process waiting for pipe space got unblocked because the reader closed the 
pipe 

1186 Cannot allocate space to a pipe while it has data wrapped around 

1188 Cannot, compact a pipe while it has data wrapped around 

1190 Attempt to access a page that is not allocated to the pipe 

1191 Bad parameter 

1193 Premature end of file encountered 

1196 Something is still open on device—cannot unmount 

1 197 Volume is not formatted or cannot be read 

1 198 Negative request count is illegal 

1199 Function or procedure is not yet implemented 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 Invalid UCSD directory 

1204 File not found 

1210 Boot track program not executable 

1211 Boot track program too big 

1212 Error reading boot track program 

1213 Error writing boot track program 

1214 Boot track program file not found 

1215 Cannot write boot tracks on that device 

1216 Could not create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Could not find configuration information entry 

1219 Could not get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

1225 Scavenger has detected an internal inconsistency symptomatic of a software 
bug 

1226 Invalid device name 

1227 Device is not block structured 

1228 Illegal attempt to scavenge the boot volume 

1229 Cannot read consistently from the volume 

1230 Cannot write consistently to the volume 

1231 Cannot allocate space (Heap segment) 

1232 Cannot allocate space (Map segment) 

1233 Cannot allocate space (SFDB segment) 
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1237 Error rebuilding the volume root directory 

1240 Illegal attempt to scavenge a non-OS-f ormatted volume 

1296 Bad string argument has Deen passed 

1297 Entry name for the object is invalid (on the volume) 

1298 S-list entry for the object is invalid (on the volume) 
1807 No disk in floppy drive 

1820 write-protect error on floppy drive 

1822 Unable to clamp floppy drive 

1824 Floppy drive write error 

1882 Bad response from ProFile 

1885 ProFile timeout error 

1998 Invalid parameter address 

1999 Badrefnum 

6001 Attempt to access unopened file 

6002 Attempt to reopen a file which is not closed using an open FIB (file info block) 

6003 Operation incompatible with access mode with which file was opened 

6004 Printer off line 

6005 File record type incompatible with character device (must be byte sized) 

6006 Bad integer (read) 

6010 Operation incompatible with file type or access mode 

6081 Premature end of exec file 

6082 Invalid exec (temporary) file name 

6083 Attempt to set prefix with null name 

6090 Attempt to move console with exec or output file open 

6101 Bad real (read) 

6151 Attempt to reinitalize heap already in use 

6152 Bad argument to NEW (negative size) 

6153 Insufficient memory for NEW request 

6154 Attempt to RELEASE outside of heap 

Operating System Error Codes 

The error codes listed below are generated only when a nonrecoverable error 
occurs while in Operating System code. 

10050 Request block is not chained to a PCB (Unblk_Req) 

10051 Bld_Req is called with interrupts off 

10100 An error was returned from SetUp_Directory or a Data Segment routine 
(Setup_IUInfo) 

10102 Error > trying to create shell (Root) 

10103 Sem_count> l(lnit_Sem) 

10104 Could not open event channel for shell (Root) 

10197 Automatic stack expansion fault occurred in system code (Check_stack) 

10198 Need_Mem set for current process while scheduling is disabled 
(SimpleScheduler) 

10199 Attempt to block for reason other than I/O while scheduling is disabled 
(SimpleScheduler) 

10201 Hardware exception occurred while in system code 

10202 No space left from Sigl_Excep call in Hard_Excep 
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10203 No space left from Sigl_Excep call in Nml_Excep 
10205 Error from Wait_Event_Chn called in Excep_Prolog 

10207 No system data space in Excep_Setup 

10208 No space left from Sigl_Excep call in range error 

10212 Error in Term_Def_Hdl from Enable_Excep 

10213 Error in Force_Term_Excep, no space in Enq_Ex_Data 
10401 Error from ciose_Event_cnn in Ec_Cleanup 

10582 Unable to get space in Freeze_Seg 
10590 Fatal memory parity error 

10593 Unable to move memory manager segment during startup 

10594 unable to swap in a segment during startup 

10595 Unable to get space in Extend_MMlist 

10596 Trying to alter size of segment tnat is not data or stack (Alt_DS_Size) 

10597 Trying to allocate space to an allocated segment (Alloc_Mem) 

10598 Attempting to allocate a nonf ree memory region (Take_Free) 

10600 Error attempting to make timer pipe 

10601 Error from Kill_Object of an existing timer pipe 

10602 Error from second Make_Pipe to make timer pipe 

10603 Error from Open to open timer pipe 

10604 No syslocal space for head of timer list 

10605 Error during allocate space for timer pipe, or interrupt from nonconfigured 
device 

10609 interrupt from nonconfigured device 

10610 Error from info about timer pipe 

10611 Spurious interrupt from floppy drive #2 

10612 Spurious interrupt from floppy drive #1, or no syslocal space for timer list 
element 

10613 Error from Read_Data of timer pipe 

10614 Actual returned from ReadJData is not the same as requested from timer 
pipe 

10615 Error from open of the receiver's event channel 

10616 Error from Write_Event to the receiver's event channel 

10617 Error from close_Event_Chn on the receiver's pipe 
10619 No sysglobal space for timer request block 

1 0624 Attempt to shut down floppy disk controller while drive is still busy 
10637 Not enough memory to initialize system timeout drives 
1 0675 Spurious timeout on console driver 

10699 Spurious timeout on parallel printer driver 

10700 Mismatch between loader version number and Operating System version 
number 

10701 OS exhausted its internal space during startup 

10702 Cannot make system process 

10703 Cannot kill pseudo-outer process 

10704 Cannot create driver 

10706 Cannot initialize floppy disk driver 

10707 Cannot initialize the File System volume 

10708 Hard disk mount table unreadable 
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10709 Cannot map screen data 

10710 Too many slot-based devices 

10724 The boot tracks do not know the right File System version 

10725 Either damaged File System or damaged contents 

10726 Boot device read failed 

10727 The OS will not fit into the available memory 

10728 SYSTEM.OS is missing 

10729 SYSTEM.CONFIG is corrupt 

10730 SYSTEM.OS is corrupt 

10731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

10732 SYSTEM.LLD is corrupt 

10733 Loader range error 

10734 Wrong driver is found. For instance, storing a diskette loader on a ProFile 

10735 SYSTEM.LLD is missing 

10736 system.unpack is missing 

10737 Unpack Of SYSTEM.OS with SYSTEM.UNPACK failed 

11176 Found a pending write request for a pipe while in eiose_Object when it is 
called tiy the last writer of the pipe 

11177 Found a pending read request for a pipe while in close_Object when it is 
called by the (only possible) reader of the pipe 

11178 Found a pending read request for a pipe while in Read_Data from the pipe 
11180 Found a pending write request for a pipe while in write_Data to the pipe 
I18xx Error xx from diskette ROM (See OS errors I8xx) 

11901 Call to Getspace or Relspace with a bad parameter, or free pool is bad 
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* defined for mounted or unmounted devices 
$ defined for mounted devices only 
All other fields are defined for mounted block-structured devices only. 



DEVICE_L VOLUMEJ": 

backup volid 
blocksize 

* blockstructured 
boot_code 
boot_environ 
clustersize 
copy 

copy_flag 
copy_thread 
datasize 

* devt 

* dir_path 
DTCC 
DTVB 
DTVC 
DTVS 
filecount 
freecount 
fs_overhead 

fs_size 
fsversion 

* iochannel 

label_size 

$ lockeddev 
machine_ID 
master 
master_copy_ID 

* mounted 

$ mount _pending 

* name 

$ opencount 
overmount_stamp 
password 



ID of the volume of which this volume is a copy. 

Number of bytes in a block on this device. 

Flag set if this device is block-structured. 

Reserved. 

Reserved. 

Reserved. 

Reserved. 

Flag set if this volume is a copy. 

Count of copy operations involving this volume. 

Number of data bytes in a page on this volume. 

Device type. 

Pathname of the volume/device. 

Date/time volume was created if it is a copy. 

Date/time volume was last backed-up. 

Date/time volume was created. 

Date/time volume was last scavenged. 

Count of files on this volume. 

Count of free pages on this volume. 

Number of pages on this volume required to store 

File System data structures. 

Number of pages on this volume. 

Version number of the File System under which 

this volume was initialized. 

Number of the expansion card channel through 

which this device is accessed. 

Size in bytes of the user-defined labels associated 

with objects on this volume. 

Reserved. 

Machine on which this volume was initialized. 

Reserved. 

Reserved. 

Flag set if a volume is mounted. 

Reserved. 

Name of this volume/device. 

Count of objects open on this volume/device. 

Reserved. 

Password of this volume. 
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$ privatedev 


Reserved. 


privileged 


Reserved. 


$ remote 


Reserved. 


result_scavenge 


Reserved. 


scavenge_flag 


Flag set by the Scavenger if it has altered this 




volume in some way. 


* slot_no 


Number of the expansion slot holding the card 




through which this device is accessed. 


$ unmount jDending 


Reserved. 


volid 


Unique identifier for this volume. 


vol_left_mounted 


Flag set if this volume was mounted during a 




system crash. 


volname 


Volume name. 


volnum 


Volume number. 


vol_size 


Total number of blocks in the File System volume 




and boot area on this device. 


write jDrotected 


Reserved. 



OBJECT T: 



acmode 
dir_path 

DTA 
DTB 
DTC 
DTM 
DTS 
eof 

etype 
file_closed_by_OS 

file_left_open 

file_scavenged 

fmark 
fs_pverhead 

ftype 

fuid 

kswitch 

locked 

lpsize 



Set of access modes associated with this refnum. 

Pathname of the directory containing this object. 

Date/time object was last accessed. 

Date/time object was last backed-up. 

Date/time object was created. 

Date/time object was last modified. 

Date/time object was last scavenged. 

Flag set if end of file has been encountered on 

this object (through the given refnum). 

Directory entry type. 

Flag set if this object was closed by the Operating 

System. 

Flag set if this object was open during a system 

crash. 

Flag set by the Scavenger if this object has been 

altered in some way. 

Absolute byte to which the file mark points. 

Number of pages used by the File System to store 

control information about this object. 

Object type. 

Unique identifier for this object. 

Flag set when the object is killed. 

Reserved. 

Number of data bytes on a page. 
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machine JD 
master_file 
name 
nreaders 

nwriters 

nusers 

private 

protected 

psize 

refnum 

result_scavenge 

safety_on 

size 

system_type 

user_type 

user_subtype 



Machine on which this object may De opened. 

Flag set if this object is a master. 

Entry name of this object. 

Number of processes with this object open for 

reading. 

Number of processes with this object open for 

writing. 

Number of processes with this object open. 

Flag set if this object is open for private access. 

Flag set if this object is protected. 

Physical size of this object in bytes. 

Reference number for this object (argument to 

INFO). 

Reserved. 

value of the safety switch for this object. 

Number of data bytes in this object (LEOF). 

Reserved. 

User-defined type field for this object. 

User-defined subtype field for this object. 
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Please note that the topic references in this Index are by section number. 

5.9.4 



accessing devices 1.3, 2.8 
ACTIVATE_PROCESS 3.8.6 
ALLOCATE 2.10.13 
Append access 2.10.8 
attribute 1.3, 2.10.5 



C0NVERT_TIME 
creating 

a data segment 4.7. 

an event channel 5. 

an object 2.10.1 

a process 3.3, 3.8. 



B 

baud rate 2.10.12.1 
binding 4.1 
BIN0_0ATASE6 4.7.12 
blocked process 1.4, 

3 (introduction), 3.8.5 
buffer 2.9, 2.10.12.1, 2.10.16, 

5.5, 5.8 



CARDS_EQUIPPED 6.1.1 

catalog 2.1, 2.5, 2.10.19 

changing file size 2.10.13-2.10.15 

clock 5.6 

clock system calls 5.9 

CL0SE_DATASEG 4.7.4 

CL0SE_EVENT_CHN 5.8.4 

CL0SE_0BJECT 2.10.9 

code segment 4.5 

communication between processes 1./ 

COMPACT 2.10.14, 2.10.15 

configuration 6 (introduction) 

configuration system calls 6.1 

controlling 

a device 2.10.12 

a process 3.4 



data segment 

creating 4.7.1 

private 4.1, 4.4 

shared 1.7, 4.1, 4.3 

swapping 4.6 
Decode mnemonics 2.10.12 
Dcdata 2.10.12 
Dctype 2.10.12 
Dcversion 2.10.12 
DECLARE_EXCEP_H0L 5.7.1 
DELAYJIME 5.9.1 
deleting 

a process 3.8.2, 3.8.4 

an object 2.10.2 
device 2.3-2.7, 2.10.12 

accessing 1.3, 2.8 

control information 2.10.12 

mounting 1.3, 2.10.20 

names 2.1, 2.3, 2.10.12.1 

priority 2.3 

storage 2.4 
DEVICE_C0NTR0L 2.10.12 
directory 2 (introduction) 
DISABLE_EXCEP 5.7.2 
disk hard error codes 2.10.12.2 
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division by zero 5.2, B 
Dread, Dwrite access 2.10.8 



FLUSH_OATASEG A. 7. 5 
FLUSH_EVENT_CHN 5.8.7 
FLUSHJXCEP 5.7.6 
FS INFO fields E 



5.7.3 
2.7, 2.10.14, 2.10.15 
see also end of file. 



2.10.12.2 



ENABLE_EXCEP 
end of file 
eof 2.10.5; 
error 

disk hard error codes 

error messages D 

soft error 2.10.12.1 

See also exception, 
event 1.6, 5.4, C 
event channel 1.7, 5.5, 5.8.1 
event management system calls 
event types C 
exception 1.6, 5.1-5.3, B 
exception handler 5.1, 5.3 
exception management system calls 

5.7 
exception names B 



5.8 



father process 1.4, 3.6, 3.7, 

3.8.1, 3.8.2 
file 2 (introduction) 

access 2.8 

attributes 2.10.5-2.10.7 

changing size 2.10.13-2.10.15 

label 2.6, 2.10.11 

marker 2.7, 2.10.15 

name 2.1, 2.10.1 

private 2.8 

shared 1.7, 2.8 
File System 1.3, 2 
File System calls 2.10 
FLUSH 2.10.16 



GET_CONFIG_NAME 6.1.2 
GET_NEXT_ENTRY 2.10.19 
GETJIME 5.9.2 
GETJ!0RKING_DIR 2.10.18 
global access to files 2.8 
global event channel 5.5 
Global Refnum 2.8, 2.10.8 



handshake 2.10.12.1 
hierarchy of processes 3.2 



„_ 1 

INFO 2.10.6 
INFO_ADDRESS 4.7.9 
INFO_DATASEG 4.7.7 
INFO_EVENT_CHN 5.8.5 
INF0_EXCEP 5.7.4 
INF0_LDSN 4.7.8 
INF0_PR0CESS 3.8.3 
interface unit A 
interprocess communication 1.7, 
1/0 2 (introduction) 



-K- 



2.9 



KILL_DATASEG 4.7.2 
KILL_EVENT_CHN 5.8.2 
KILL_08JECT 2.10.2 
KILL PROCESS 3.8.4 



lndex-2 



Operating System Reference Manual 



index 



4.2, 



label, file 2.6, 2.10.11 
LDSN A. 2, 4.4, 4.7.8 
LEOF. See end of file, 
local data segment 4.1 
local event channel 5.5 
logical data segment number 

4.4, 4.7.8 
logical end of file. See end of 

file. 
LOOKUP 2.10.5 



-M- 



MAKE_DATASEG 4.7.1 

MAKE_EVENT_CHN 5.8.1 

MAKE_FILE 2.10.1 

MAKE_PIPE 2.10.1 

MAKE_PROCESS 3.8.1 

memory management 1.5, 4.1-4.6 

memory management system calls 



4.7 



memory, parameter 6 (introduction) 

MEM_INF0 4.7.10 

mnemonics for Decode 2.10.12.1 

MOUNT 2.10.20 

mounting a device 1.3, 2.10.20 

MY ID 3.8.9 
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naming an object 
2.10.4 



2.1, 2.10.1, 





object 1.3 

creating 2.10.1 
deleting 2.10.2 
naming 2.1, 2.10.1 
renaming 2.10.4 



OPEN 2.10.8 
0PEN_DATASEG 4.7.3 
OPEN_EVENT_CHN 5.8.3 
OS interface A 
0SB00TV0L 6.1.3 



page 2.4 

parameter memory 6 (introduction) 

parity 2.10.12.1 

pathname 1.3, 2.1, 2.2 

PEOF. See end of file. 

physical end of file. See end of 

file, 
pipe 1.7, 2.9. 2.10.1, 2.10.8 
priority of devices 2.3 
priority of processes 3.5, 3.8.7, 

3.8.8 
private access to files 2.8, 2.10J 
private data segment 4.1, 4.4 
process 1.4, 3 

blocked 1.4, 3 (introduction), 
3.8.5 

creating 3.3, 3.8.1 

father 1.4, 3.6, 3.7, 3.8.1, 
3.8.2 

hierarchy 3.2 

priority 3.5, 3.8.7, 3.8.8 

queuing 3.5, 3.8.5-3.8.8 

scheduling 3.5, 3.8.5-3.8.8 

shell 1.4, 3.2 

son 1.4, 3.7, C 

starting 3.8.1, 3.8.6 

Stopping 3.8.2, 3.8.4 

structure 3.1 

termination 1.4, 3.6, 5.2, B, C 
process system calls 3.8 
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queuing a process 3.5, 3.8.5-3.8.8 



-R- 



range check error 5.2, B 
READ_DATA 2.10.10 
READ_LABEL 2.10.11 
refnum 2.8; see also Global_Refnum. 
RENAME_ENTRY 2.10.4 
renaming an object 2.10.4 
RESET_CATAL06 2.10.19 
running a program 1.4, 1.9, 3.8.1, 
3.8.6 



safety switch 2.5, 2.10.17 

Scheduler 3 

scheduling processes 3.5, 

3.8.5-3.8.8 
SEND_EVENT_CHN 5.8.8 
SETACCESS_DATASEG 4.7.11 
SETPRIORITY_PROCESS 3.8.7 
SET_FILE_INF0 2.10.7 
SET_L0CAL_TIME_DIFF 5.9.3 
SET_SAFETY 2.10.17 
SET_W0RKING_DIR 2 . 10 . 18 
shared data segment 1.7, 4.1, 4.3 
shared file 1.7, 2.8 
shell process 1.4, 3.2 
SIGNAL_EXCEP 5.7.5 
SIZE_DATASEG 4.7.6 
soft error 2.10.12.1 
son process 1.4, 3.7, C 
sparing 2.10.12 

starting a process 3.8.1, 3.8.6 
stopping a process 3.8.2, 3.8.4 
storage device 2.4 
SUSPEND PROCESS 3.8.5 



swapping 4.6 
Syscall unit A 
system calls 

clock 5.9 

configuration 6 . 1 

event management 5.8 

exception management 5.7 

file 2.10 

memory management 4.7 

process 3.8 
system clock 5.6, 5.9 
system- defined exceptions 5.2, B 
SYSJDVERFLOW 5.2, B 
SYS_S0N_TERM C 
SYS_TERMINATE 5.2, B 
SYS_VALUEJ)0B 5.2, B 
SYS_ZER0 DIV 5.2, B 



terminated process 1.4, 3.6, 5.2, 

B, C 
TER(iINATE_PROCESS 3.8.2 
timed events 5.8.8 
tree, process 3.2 
TRUNCATE 2.10.15 



-U- 



UNBIND_DATASEG 4.7.12 
UNKILLJILE 2.10.3 
UNMOUNT 2.10.20 
user-defined exception handler 



5.3 



-V- 



value out of bounds 5.2, B 
volume catalog 2.1, 2.5, 2. 
volume name 1.3 



10.19 
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WAIT_EVENT_CHN 5.8.6 
working directory 2.2 
working set 4.2 
WRITE_DATA 2.10.10 
WRITE_LABEL 2.10.11 
writing buffered data 2.10.16 



Y 

YIELD CPU 3.8.8 
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